{ "openapi": "3.0.3", "info": { "title": "Tapfiliate REST API", "version": "1.6", "description": "Reference for the Tapfiliate REST API. See the introduction for authentication, pagination and rate limits.", "x-generated-from": "ApiBlueprint@e23e51f" }, "servers": [ { "url": "https://api.tapfiliate.com/1.6", "description": "Production" } ], "paths": { "/customers/{id}/": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerModel" }, "example": { "id": "cu_eXampl3", "customer_id": "USER123", "status": "trial", "created_at": "2021-07-02T09:55:20+00:00", "click": { "created_at": "2021-03-03T12:39:19+0000", "referrer": "https://example-blog.inc/check-out-johns-product/", "landing_page": "https://tapper.inc/johns-cool-product/" }, "program": { "id": "johns-affiliate-program", "title": "John's affiliate program", "currency": "USD" }, "affiliate": { "id": "janejameson", "firstname": "Jane", "lastname": "Jameson" }, "affiliate_meta_data": { "subid1": "baz" }, "meta_data": { "foo": "bar" }, "warnings": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Retrieve a customer", "operationId": "retrieveACustomer", "tags": [ "Customers" ], "parameters": [ { "name": "id", "in": "path", "description": "The Tapfiliate generated `id` of the Customer to perform action with.", "required": true, "example": "cu_eXampl3", "schema": { "type": "string" } } ] }, "patch": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "customer_id": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string" }, "click": { "type": "object", "properties": { "created_at": { "type": "string" }, "referrer": { "type": "string" }, "landing_page": { "type": "string" } } }, "program": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "currency": { "type": "string" } } }, "affiliate": { "type": "object", "properties": { "id": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" } } }, "affiliate_meta_data": { "type": "object", "properties": { "subid1": { "type": "string" } } }, "meta_data": { "type": "object", "properties": { "buz": { "type": "string" } } }, "warnings": { "nullable": true } } }, "example": { "id": "cu_eXampl3", "customer_id": "USER456", "status": "trial", "created_at": "2021-07-02T09:55:20+00:00", "click": { "created_at": "2021-03-03T12:39:19+0000", "referrer": "https://example-blog.inc/check-out-johns-product/", "landing_page": "https://tapper.inc/johns-cool-product/" }, "program": { "id": "johns-affiliate-program", "title": "John's affiliate program", "currency": "USD" }, "affiliate": { "id": "janejameson", "firstname": "Jane", "lastname": "Jameson" }, "affiliate_meta_data": { "subid1": "baz" }, "meta_data": { "buz": "baz" }, "warnings": null } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Update a customer", "operationId": "updateACustomer", "tags": [ "Customers" ], "parameters": [ { "name": "id", "in": "path", "description": "The Tapfiliate generated `id` of the Customer to perform action with.", "required": true, "example": "cu_eXampl3", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "customer_id": "USER456", "meta_data": { "buz": "baz" } }, "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "example": "foobar1", "description": "The id for this customer in your system. The customer id should be unique for each customer." } } } } } }, "x-mint": { "metadata": { "playground": "simple" } } }, "delete": { "responses": { "204": { "description": "No Content", "headers": {}, "content": {} }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Delete a customer", "operationId": "deleteACustomer", "tags": [ "Customers" ], "parameters": [ { "name": "id", "in": "path", "description": "The Tapfiliate generated `id` of the Customer to perform action with.", "required": true, "example": "cu_eXampl3", "schema": { "type": "string" } } ], "x-mint": { "metadata": { "playground": "simple" } } } }, "/customers/": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomersCollectionModel" }, "example": [ { "id": "cu_eXampl3", "customer_id": "USER123", "status": "trial", "created_at": "2021-07-02T09:55:20+00:00", "click": { "created_at": "2021-03-03T12:39:19+0000", "referrer": "https://example-blog.inc/check-out-johns-product/", "landing_page": "https://tapper.inc/johns-cool-product/" }, "program": { "id": "johns-affiliate-program", "title": "John's affiliate program", "currency": "USD" }, "affiliate": { "id": "janejameson", "firstname": "Jane", "lastname": "Jameson" }, "affiliate_meta_data": { "subid1": "baz" }, "meta_data": { "foo": "bar" }, "warnings": null } ] } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "summary": "List all customers", "operationId": "listAllCustomers", "tags": [ "Customers" ], "parameters": [ { "name": "program_id", "in": "query", "description": "The program Id", "example": "johns-affiliate-program", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "description": "The id for this customer in your system. The customer id should be unique for each customer.", "example": "USER123", "schema": { "type": "string" } }, { "name": "affiliate_id", "in": "query", "description": "The affiliate Id", "example": "janejameson", "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "description": "Date From", "example": "2022-01-01", "schema": { "type": "string" } }, { "name": "date_to", "in": "query", "description": "Date To", "example": "2099-12-31", "schema": { "type": "string" } } ] }, "post": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "customer_id": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string" }, "click": { "nullable": true }, "program": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "currency": { "type": "string" } } }, "affiliate": { "type": "object", "properties": { "id": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" } } }, "affiliate_meta_data": { "nullable": true }, "meta_data": { "type": "object", "properties": { "tim": { "type": "string" } } }, "warnings": { "nullable": true } } }, "example": { "id": "cu_0Th3r", "customer_id": "USER789", "status": "trial", "created_at": "2021-07-02T09:55:20+00:00", "click": null, "program": { "id": "johns-affiliate-program", "title": "John's affiliate program", "currency": "USD" }, "affiliate": { "id": "janejameson", "firstname": "Jane", "lastname": "Jameson" }, "affiliate_meta_data": null, "meta_data": { "tim": "tam" }, "warnings": null } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "summary": "Create a customer", "operationId": "createACustomer", "description": "You are required to use either a Tracking id, referral code, click id, coupon code, or asset_id & source_id combination. If more than one of these is sent, the precedence will be as follows (highest to lowest): Coupon, Referral Code, Click Id, Asset id + Source id, Tracking id\n\nPlease refer to our [REST API integration guide](https://support.tapfiliate.com/en/articles/12682358-how-to-integrate-with-tapfiliate-via-the-rest-api) for more info.", "tags": [ "Customers" ], "parameters": [ { "name": "override_max_cookie_time", "in": "query", "description": "", "schema": { "type": "boolean", "default": "false" } } ], "requestBody": { "content": { "application/json": { "example": { "coupon": "JANE10OFF", "customer_id": "USER789", "status": "trial", "meta_data": { "tim": "tam" }, "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.100 Safari/537.36", "ip": "111.11.11.111" }, "schema": { "type": "object", "required": [ "customer_id" ], "properties": { "referral_code": { "type": "string", "example": "janejameson", "description": "An affiliate's referral code. This corresponds to the value of `ref=` in their referral link" }, "tracking_id": { "type": "string", "example": "XXXXX", "description": "XXX-XXXX-XXXX-XXXXX (string) - The tracking id, to be retrieved from our javascript library. Please refer to our [REST API integration guide](https://support.tapfiliate.com/en/articles/12682358-how-to-integrate-with-tapfiliate-via-the-rest-api) for more info." }, "click_id": { "type": "string", "example": "id: 1", "description": "abc (string, optional) - The click id. Used to add additional reporting information." }, "coupon": { "type": "string", "example": "JANE10OFF", "description": "A coupon code to track the conversion by" }, "asset_id": { "type": "string", "example": "1-aaaaaa", "description": "The asset id" }, "source_id": { "type": "string", "example": "1-ssssss", "description": "The source id" }, "customer_id": { "type": "string", "example": "USER123", "description": "The id for this customer in your system. The customer id should be unique for each customer." }, "status": { "type": "string", "example": "trial|lead|new", "description": "Determines the intial status for the customer. You can read more about [statuses here](https://support.tapfiliate.com/en/articles/3092024-what-are-customers#customer-status). Defaults to \"new\" if none is passed." }, "user_agent": { "type": "string", "example": "ua string", "description": "The client's user agent string. Used for statistics and fraud detection." }, "ip": { "type": "string", "example": "111.11.11.111", "description": "The client's ip. Used for fraud detection." } } } } } }, "x-mint": { "metadata": { "playground": "simple" } } } }, "/customers/{id}/status/": { "delete": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "customer_id": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string" }, "click": { "type": "object", "properties": { "created_at": { "type": "string" }, "referrer": { "type": "string" }, "landing_page": { "type": "string" } } }, "program": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "currency": { "type": "string" } } }, "affiliate": { "type": "object", "properties": { "id": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" } } }, "affiliate_meta_data": { "type": "object", "properties": { "subid1": { "type": "string" } } }, "meta_data": { "type": "object", "properties": { "foo": { "type": "string" } } }, "warnings": { "nullable": true } } }, "example": { "id": "cu_eXampl3Pay1ng", "customer_id": "USER666", "status": "canceled", "created_at": "2021-07-02T09:55:20+00:00", "click": { "created_at": "2021-03-03T12:39:19+0000", "referrer": "https://example-blog.inc/check-out-johns-product/", "landing_page": "https://tapper.inc/johns-cool-product/" }, "program": { "id": "johns-affiliate-program", "title": "John's affiliate program", "currency": "USD" }, "affiliate": { "id": "janejameson", "firstname": "Jane", "lastname": "Jameson" }, "affiliate_meta_data": { "subid1": "baz" }, "meta_data": { "foo": "bar" }, "warnings": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Cancel a customer", "operationId": "cancelACustomer", "tags": [ "Customers" ], "parameters": [ { "name": "id", "in": "path", "description": "The Tapfiliate generated `id` of the customer.", "required": true, "example": "cu_eXampl3Pay1ng", "schema": { "type": "string" } } ], "x-mint": { "metadata": { "playground": "simple" } } }, "put": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "customer_id": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string" }, "click": { "type": "object", "properties": { "created_at": { "type": "string" }, "referrer": { "type": "string" }, "landing_page": { "type": "string" } } }, "program": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "currency": { "type": "string" } } }, "affiliate": { "type": "object", "properties": { "id": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" } } }, "affiliate_meta_data": { "type": "object", "properties": { "subid1": { "type": "string" } } }, "meta_data": { "type": "object", "properties": { "foo": { "type": "string" } } }, "warnings": { "nullable": true } } }, "example": { "id": "cu_eXampl3Pay1ng", "customer_id": "USER666", "status": "paying", "created_at": "2021-07-02T09:55:20+00:00", "click": { "created_at": "2021-03-03T12:39:19+0000", "referrer": "https://example-blog.inc/check-out-johns-product/", "landing_page": "https://tapper.inc/johns-cool-product/" }, "program": { "id": "johns-affiliate-program", "title": "John's affiliate program", "currency": "USD" }, "affiliate": { "id": "janejameson", "firstname": "Jane", "lastname": "Jameson" }, "affiliate_meta_data": { "subid1": "baz" }, "meta_data": { "foo": "bar" }, "warnings": null } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Uncancel a customer", "operationId": "uncancelACustomer", "description": "The customer will jump back to the appropriate status. You can read more about status [statuses here](https://support.tapfiliate.com/en/articles/3092024-what-are-customers#customer-status)", "tags": [ "Customers" ], "parameters": [ { "name": "id", "in": "path", "description": "The Tapfiliate generated `id` of the customer.", "required": true, "example": "cu_eXampl3Pay1ng", "schema": { "type": "string" } } ], "x-mint": { "metadata": { "playground": "simple" } } } }, "/customers/{id}/meta-data/": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "foo": { "type": "string" } } }, "example": { "foo": "bar" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Retrieve meta data", "operationId": "retrieveMetaData", "tags": [ "Customers" ], "parameters": [ { "name": "id", "in": "path", "description": "The Tapfiliate generated `id` of the customer.", "required": true, "example": "cu_eXampl3", "schema": { "type": "string" } } ] }, "put": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "foo": { "type": "string" }, "baz": { "type": "string" } } }, "example": { "foo": "bar", "baz": "qux" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Update (replace) meta data", "operationId": "updateReplaceMetaData", "tags": [ "Customers" ], "parameters": [ { "name": "id", "in": "path", "description": "The Tapfiliate generated `id` of the customer.", "required": true, "example": "cu_eXampl3", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "foo": "bar", "baz": "qux" }, "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "example": "value", "description": "A key value pair. Multiple allowed" } } } } } }, "x-mint": { "metadata": { "playground": "simple" } } } }, "/customers/{id}/meta-data/{key}/": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string" } } }, "example": { "value": "bar" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Retrieve meta data by key", "operationId": "retrieveMetaDataByKey", "tags": [ "Customers" ], "parameters": [ { "name": "id", "in": "path", "description": "The Tapfiliate generated `id` of the customer.", "required": true, "example": "cu_eXampl3", "schema": { "type": "string" } }, { "name": "key", "in": "path", "description": "The meta data `key`.", "required": true, "example": "foo", "schema": { "type": "string" } } ] }, "put": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string" } } }, "example": { "value": "bar" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Set meta data by key", "operationId": "setMetaDataByKey", "tags": [ "Customers" ], "parameters": [ { "name": "id", "in": "path", "description": "The Tapfiliate generated `id` of the customer.", "required": true, "example": "cu_eXampl3", "schema": { "type": "string" } }, { "name": "key", "in": "path", "description": "The meta data `key`.", "required": true, "example": "foo", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "value": "bar" }, "schema": { "type": "object", "required": [ "value" ], "properties": { "value": { "type": "string", "example": "Bar", "description": "The value to set for the given key" } } } } } }, "x-mint": { "metadata": { "playground": "simple" } } }, "delete": { "responses": { "204": { "description": "No Content", "headers": {}, "content": {} }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Delete meta data by key", "operationId": "deleteMetaDataByKey", "tags": [ "Customers" ], "parameters": [ { "name": "id", "in": "path", "description": "The Tapfiliate generated `id` of the customer.", "required": true, "example": "cu_eXampl3", "schema": { "type": "string" } }, { "name": "key", "in": "path", "description": "The meta data `key`.", "required": true, "example": "foo", "schema": { "type": "string" } } ], "x-mint": { "metadata": { "playground": "simple" } } } }, "/conversions/{conversion_id}/": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversionModel" }, "example": { "id": 1, "external_id": "ORD123", "amount": 550, "click": { "created_at": "2021-03-03T12:39:19+0000", "referrer": "https://example-blog.inc/check-out-johns-product/", "landing_page": "https://tapper.inc/johns-cool-product/" }, "commissions": [ { "id": 1, "conversion_sub_amount": 550, "amount": 55, "commission_type": "standard", "approved": true, "affiliate": { "id": "janejameson", "firstname": "Jane", "lastname": "Jameson" }, "kind": "regular", "currency": "USD", "created_at": null, "payout": null, "comment": null, "final": null, "commission_name": "standard" } ], "program": { "id": "johns-affiliate-program", "title": "John's affiliate program", "currency": "USD" }, "affiliate": { "id": "janejameson", "firstname": "Jane", "lastname": "Jameson" }, "customer": { "id": "cu_eXampl30th3r", "customer_id": "USER999", "status": "paying" }, "affiliate_meta_data": { "subid1": "baz" }, "meta_data": { "foo": "bar", "tap": "awesome" }, "created_at": "2021-03-03T12:39:19+0000", "warnings": null, "tracking_source": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Retrieve a conversion", "operationId": "retrieveAConversion", "tags": [ "Conversions" ], "parameters": [ { "name": "conversion_id", "in": "path", "description": "Numeric `id` of the conversion to perform action with.", "required": true, "example": "1", "schema": { "type": "number" } } ] }, "patch": { "responses": { "200": { "description": "OK", "headers": {}, "content": {} }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Update a conversion", "operationId": "updateAConversion", "tags": [ "Conversions" ], "parameters": [ { "name": "conversion_id", "in": "path", "description": "Numeric `id` of the conversion to perform action with.", "required": true, "example": "1", "schema": { "type": "number" } }, { "name": "recalculate_commissions", "in": "query", "description": "Also re-calculate commissions when changing the Conversion amount", "schema": { "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "example": { "amount": 17.95, "external_id": "ORD123", "meta_data": { "baz": "qux" } }, "schema": { "type": "object", "properties": { "amount": { "type": "number", "example": 30.55, "description": "The new amount for the commission" }, "external_id": { "type": "string", "example": "foobar1", "description": "A unique id for this conversion. It can be anything that is meaningful to you, like an order number, user id, email adres etc.. After a conversion has taken place, you can find this id alongside the conversion on our platform." } } } } } }, "x-mint": { "metadata": { "playground": "simple" } } }, "delete": { "responses": { "204": { "description": "No Content", "headers": {}, "content": {} }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Delete a conversion", "operationId": "deleteAConversion", "tags": [ "Conversions" ], "parameters": [ { "name": "conversion_id", "in": "path", "description": "Numeric `id` of the conversion to perform action with.", "required": true, "example": "1", "schema": { "type": "number" } } ], "x-mint": { "metadata": { "playground": "simple" } } } }, "/conversions/": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversionsCollectionModel" }, "example": [ { "id": 1, "external_id": "ORD123", "amount": 550, "click": { "created_at": "2021-03-03T12:39:19+0000", "referrer": "https://example-blog.inc/check-out-johns-product/", "landing_page": "https://tapper.inc/johns-cool-product/" }, "commissions": [ { "id": 1, "conversion_sub_amount": 550, "amount": 55, "commission_type": "standard", "approved": true, "affiliate": { "id": "janejameson", "firstname": "Jane", "lastname": "Jameson" }, "kind": "regular", "currency": "USD", "created_at": null, "payout": null, "comment": null, "final": null, "commission_name": "standard" } ], "program": { "id": "johns-affiliate-program", "title": "John's affiliate program", "currency": "USD" }, "affiliate": { "id": "janejameson", "firstname": "Jane", "lastname": "Jameson" }, "customer": { "id": "cu_eXampl30th3r", "customer_id": "USER999", "status": "paying" }, "meta_data": { "foo": "bar", "tap": "awesome" }, "created_at": "2021-03-03T12:39:19+0000", "warnings": null, "affiliate_meta_data": { "subid1": "baz" }, "tracking_source": null } ] } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "summary": "List all conversions", "operationId": "listAllConversions", "tags": [ "Conversions" ], "parameters": [ { "name": "program_id", "in": "query", "description": "The program Id", "example": "johns-affiliate-program", "schema": { "type": "string" } }, { "name": "external_id", "in": "query", "description": "The external Id. This is the unique id from your system or shopping cart. This id was passed when the conversions was first tracked.", "example": "ORD123", "schema": { "type": "string" } }, { "name": "affiliate_id", "in": "query", "description": "The affiliate Id", "example": "janejameson", "schema": { "type": "string" } }, { "name": "pending", "in": "query", "description": "Only show conversions that have pending commissions", "schema": { "type": "boolean" } }, { "name": "date_from", "in": "query", "description": "Date From, a day in UTC", "example": "2022-01-01", "schema": { "type": "string" } }, { "name": "date_to", "in": "query", "description": "Date To, a day in UTC", "example": "2099-12-31", "schema": { "type": "string" } }, { "name": "use_profile_timezone", "in": "query", "description": "Deprecated, has no effect: time in Tapfiliate is UTC for every account, so `date_from` and `date_to` are always days in UTC", "schema": { "type": "boolean" } } ] }, "post": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number" }, "external_id": { "type": "string" }, "amount": { "type": "number" }, "click": { "nullable": true }, "commissions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "conversion_sub_amount": { "type": "number" }, "amount": { "type": "number" }, "commission_type": { "type": "string" }, "approved": { "nullable": true }, "affiliate": { "type": "object", "properties": { "id": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" } } }, "kind": { "type": "string" }, "currency": { "type": "string" }, "created_at": { "type": "string" }, "payout": { "nullable": true }, "comment": { "nullable": true }, "final": { "nullable": true }, "commission_name": { "type": "string" } }, "required": [ "id", "conversion_sub_amount", "amount", "commission_type", "approved", "kind", "affiliate", "currency", "created_at", "payout", "comment", "final", "commission_name" ] } }, "program": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "currency": { "type": "string" } } }, "affiliate": { "type": "object", "properties": { "id": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" } } }, "customer": { "nullable": true }, "meta_data": { "type": "object", "properties": { "foo": { "type": "string" } } }, "created_at": { "type": "string" }, "warnings": { "nullable": true }, "affiliate_meta_data": { "nullable": true } } }, "example": { "id": 2, "external_id": "ORD005", "amount": 100, "click": null, "commissions": [ { "id": 2, "conversion_sub_amount": 100, "amount": 10, "commission_type": "standard", "approved": null, "affiliate": { "id": "janejameson", "firstname": "Jane", "lastname": "Jameson" }, "kind": "regular", "currency": "EUR", "created_at": "2021-03-03T12:39:19+0000", "payout": null, "comment": null, "final": null, "commission_name": "standard" }, { "id": 3, "conversion_sub_amount": 100, "amount": 5, "commission_type": "level-2", "approved": null, "kind": "level", "affiliate": { "id": "sandrasanderson", "firstname": "Sandra", "lastname": "Sanderson" }, "currency": "EUR", "created_at": "2021-03-03T12:39:19+0000", "payout": null, "comment": null, "final": null, "commission_name": "Level 2" } ], "program": { "id": "johns-affiliate-program", "title": "John's affiliate program", "currency": "USD" }, "affiliate": { "id": "janejameson", "firstname": "Jane", "lastname": "Jameson" }, "customer": null, "meta_data": { "foo": "bar" }, "created_at": "2021-03-03T12:39:19+0000", "warnings": null, "affiliate_meta_data": null } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "summary": "Create a conversion", "operationId": "createAConversion", "description": "You are required to use either a referral code, customer_id, click id, coupon code, tracking id, or asset_id & source_id combination. If more than one of these is sent, the precedence will be as follows (highest to lowest): Customer id, Coupon, Referral Code, Click Id, Asset id + Source id, Tracking id", "tags": [ "Conversions" ], "parameters": [ { "name": "override_max_cookie_time", "in": "query", "description": "", "schema": { "type": "boolean", "default": "false" } } ], "requestBody": { "content": { "application/json": { "example": { "coupon": "JANE10OFF", "external_id": "ORD005", "amount": 100, "currency": "EUR", "meta_data": { "foo": "bar" }, "program_group": "my-group", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.100 Safari/537.36", "ip": "111.11.11.111" }, "schema": { "type": "object", "properties": { "referral_code": { "type": "string", "example": "janejameson", "description": "An affiliate's referral code. This corresponds to the value of `ref=` in their referral link." }, "tracking_id": { "type": "string", "example": "XXXXX", "description": "XXX-XXXX-XXXX-XXXXX (string) - The tracking id, to be retrieved from our javascript library. Please refer to our [REST API integration guide](https://support.tapfiliate.com/en/articles/12682358-how-to-integrate-with-tapfiliate-via-the-rest-api) for more info." }, "click_id": { "type": "string", "example": "1-abc", "description": "The click id. Used to add additional reporting information." }, "coupon": { "type": "string", "example": "JANE10OFF", "description": "A coupon code to track the conversion by" }, "currency": { "type": "string", "example": "USD", "description": "The three letter ISO currency code. Override the program's default currency for this conversion by explicitely passing a currency code." }, "asset_id": { "type": "string", "example": "1-aaaaaa", "description": "The asset id" }, "source_id": { "type": "string", "example": "1-ssssss", "description": "The source id" }, "external_id": { "type": "string", "example": "foobar1", "description": "A unique id for this conversion. It can be anything that is meaningful to you, like an order number, user id, email adres etc.. After a conversion has taken place, you can find this id alongside the conversion on our platform. This makes it very easy to cross-reference data on our platform with your own administration. This id has to be unique for every conversion." }, "amount": { "type": "number", "example": 30.55, "description": "The conversion amount" }, "customer_id": { "type": "string", "example": "USER123", "description": "The id for the current customer in your system. Depending on your program settings, this can be used for recurring / lifetime commissions. You can read more [about this here](https://support.tapfiliate.com/en/articles/12682358-how-to-integrate-with-tapfiliate-via-the-rest-api)" }, "commission_type": { "type": "string", "example": "mycommissiontype", "description": "If no commission type is supplied, the programs default commission type is used" }, "commissions": { "type": "array", "items": {}, "description": "Will override \"amount\" and \"commission_type\" if set" }, "program_group": { "type": "string", "example": "myprogramgroup", "description": "The program group id" }, "user_agent": { "type": "string", "example": "ua string", "description": "The client's user agent string. Used for statistics and fraud detection." }, "ip": { "type": "string", "example": "111.11.11.111", "description": "The client's ip. Used for fraud detection." } } } } } }, "x-mint": { "metadata": { "playground": "simple" } } } }, "/conversions/{conversion_id}/commissions/": { "post": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "conversion_sub_amount": { "type": "number" }, "amount": { "type": "number" }, "commission_type": { "type": "string" }, "approved": { "nullable": true }, "kind": { "type": "string" }, "affiliate": { "type": "object", "properties": { "id": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" } } }, "currency": { "type": "string" }, "created_at": { "type": "string" }, "payout": { "nullable": true }, "comment": { "type": "string", "nullable": true }, "final": { "nullable": true }, "commission_name": { "type": "string" } }, "required": [ "id", "conversion_sub_amount", "amount", "commission_type", "approved", "kind", "affiliate", "currency", "created_at", "payout", "comment", "final", "commission_name" ] } }, "example": [ { "id": 3, "conversion_sub_amount": 20, "amount": 2, "commission_type": "standard", "approved": null, "kind": "regular", "affiliate": { "id": "janejameson", "firstname": "Jane", "lastname": "Jameson" }, "currency": "USD", "created_at": "2021-03-03T12:39:19+0000", "payout": null, "comment": "Awesome!", "final": null, "commission_name": "standard" }, { "id": 4, "conversion_sub_amount": 20, "amount": 1, "commission_type": "level-2", "approved": null, "kind": "level", "affiliate": { "id": "sandrasanderson", "firstname": "Sandra", "lastname": "Sanderson" }, "currency": "USD", "created_at": "2021-03-03T12:39:19+0000", "payout": null, "comment": null, "final": null, "commission_name": "Level 2" } ] } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Add commissions to a conversion", "operationId": "addCommissionsToAConversion", "tags": [ "Conversions" ], "parameters": [ { "name": "conversion_id", "in": "path", "description": "Numeric `id` of the conversion to add the commission(s) to.", "required": true, "example": "1", "schema": { "type": "number" } } ], "requestBody": { "content": { "application/json": { "example": [ { "conversion_sub_amount": 20, "comment": "Awesome!" } ], "schema": { "type": "object", "required": [ "conversion_sub_amount" ], "properties": { "conversion_sub_amount": { "type": "number", "example": 50, "description": "The amount on which the commission should be calculated using the supplied, or the program's default commission type" }, "commission_type": { "type": "string", "example": "mycommissiontype", "description": "If no commission type is supplied, the programs default commission type is used" }, "comment": { "type": "string", "example": "Awesome!", "description": "A comment for this commission. The comment will be visible to the affiliate" } } } } } }, "x-mint": { "metadata": { "playground": "simple" } } } }, "/conversions/{conversion_id}/meta-data/": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "foo": { "type": "string" }, "tap": { "type": "string" } } }, "example": { "foo": "bar", "tap": "awesome" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Retrieve meta data", "operationId": "retrieveMetaData2", "tags": [ "Conversions" ], "parameters": [ { "name": "conversion_id", "in": "path", "description": "The `id` of the conversion.", "required": true, "example": "1", "schema": { "type": "number" } } ] }, "put": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "foo": { "type": "string" }, "baz": { "type": "string" } } }, "example": { "foo": "bar", "baz": "qux" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Update (replace) meta data", "operationId": "updateReplaceMetaData2", "tags": [ "Conversions" ], "parameters": [ { "name": "conversion_id", "in": "path", "description": "The `id` of the conversion.", "required": true, "example": "1", "schema": { "type": "number" } } ], "requestBody": { "content": { "application/json": { "example": { "foo": "bar", "baz": "qux" }, "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "example": "value", "description": "A key value pair. Multiple allowed" } } } } } }, "x-mint": { "metadata": { "playground": "simple" } } } }, "/conversions/{conversion_id}/meta-data/{key}/": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string" } } }, "example": { "value": "bar" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Retrieve meta data by key", "operationId": "retrieveMetaDataByKey2", "tags": [ "Conversions" ], "parameters": [ { "name": "conversion_id", "in": "path", "description": "The `id` of the conversion.", "required": true, "example": "1", "schema": { "type": "number" } }, { "name": "key", "in": "path", "description": "The meta data `key`.", "required": true, "example": "foo", "schema": { "type": "string" } } ] }, "put": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string" } } }, "example": { "value": "bar" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Set meta data by key", "operationId": "setMetaDataByKey2", "tags": [ "Conversions" ], "parameters": [ { "name": "conversion_id", "in": "path", "description": "The `id` of the conversion.", "required": true, "example": "1", "schema": { "type": "number" } }, { "name": "key", "in": "path", "description": "The meta data `key`.", "required": true, "example": "foo", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "value": "bar" }, "schema": { "type": "object", "required": [ "value" ], "properties": { "value": { "type": "string", "example": "Bar", "description": "The value to set for the given key" } } } } } }, "x-mint": { "metadata": { "playground": "simple" } } }, "delete": { "responses": { "204": { "description": "No Content", "headers": {}, "content": {} }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Delete meta data by key", "operationId": "deleteMetaDataByKey2", "tags": [ "Conversions" ], "parameters": [ { "name": "conversion_id", "in": "path", "description": "The `id` of the conversion.", "required": true, "example": "1", "schema": { "type": "number" } }, { "name": "key", "in": "path", "description": "The meta data `key`.", "required": true, "example": "foo", "schema": { "type": "string" } } ], "x-mint": { "metadata": { "playground": "simple" } } } }, "/commissions/{commission_id}/": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommissionModel" }, "example": { "id": 1, "conversion_sub_amount": 550, "amount": 55, "commission_type": "standard", "approved": true, "affiliate": { "id": "janejameson", "firstname": "Jane", "lastname": "Jameson" }, "conversion": { "id": 1 }, "kind": "regular", "currency": "USD", "created_at": null, "payout": null, "comment": null, "final": null, "finalization_date": null, "commission_name": "standard" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Retrieve a commission", "operationId": "retrieveACommission", "tags": [ "Commissions" ], "parameters": [ { "name": "commission_id", "in": "path", "description": "Numeric `id` of the commission to perform action with.", "required": true, "example": "1", "schema": { "type": "number" } } ] }, "patch": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number" }, "amount": { "type": "number" }, "approved": { "type": "boolean" }, "created_at": { "type": "string" }, "commission_type": { "type": "string" }, "conversion_sub_amount": { "type": "number" }, "comment": { "type": "string" }, "conversion": { "type": "object", "properties": { "id": { "type": "number" } } }, "payout": { "nullable": true }, "affiliate": { "type": "object", "properties": { "id": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" } } }, "kind": { "type": "string" }, "currency": { "type": "string" }, "final": { "nullable": true }, "finalization_date": { "nullable": true }, "commission_name": { "type": "string" } } }, "example": { "id": 1, "amount": 30.55, "approved": true, "created_at": "2021-03-31T08:21:02+0000", "commission_type": "standard", "conversion_sub_amount": 550, "comment": "Amount adjusted because of returned item", "conversion": { "id": 1 }, "payout": null, "affiliate": { "id": "janejameson", "firstname": "Jane", "lastname": "Jameson" }, "kind": "regular", "currency": "USD", "final": null, "finalization_date": null, "commission_name": "standard" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Update a commission", "operationId": "updateACommission", "tags": [ "Commissions" ], "parameters": [ { "name": "commission_id", "in": "path", "description": "Numeric `id` of the commission to perform action with.", "required": true, "example": "1", "schema": { "type": "number" } } ], "requestBody": { "content": { "application/json": { "example": { "amount": 30.55, "comment": "Amount adjusted because of returned item" }, "schema": { "type": "object", "properties": { "amount": { "type": "number", "example": 30.55, "description": "The new amount for the commission" }, "comment": { "type": "string", "example": "\"foo bar\"", "description": "A comment for this commission. The comment will be visible to the affiliate" }, "approved": { "type": "boolean", "example": true, "description": "Approve or disapprove commission" }, "conversion_sub_amount": { "type": "number", "example": 50.01, "description": "The new value for the commission and it's conversion (will be recalculated)" } } } } } }, "x-mint": { "metadata": { "playground": "simple" } } } }, "/commissions/": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommissionsCollectionModel" }, "example": [ { "id": 111, "amount": 5, "approved": true, "created_at": "2021-04-01T04:23:02+0000", "commission_type": "sales-bonus", "comment": null, "conversion": null, "payout": null, "affiliate": { "id": "janejameson", "firstname": "Jane", "lastname": "Jameson" }, "kind": "bonus", "currency": "EUR", "final": null, "finalization_date": null, "commission_name": "Sales bonus" }, { "id": 2, "amount": 30, "approved": true, "created_at": "2021-04-01T04:23:02+0000", "commission_type": "standard", "conversion_sub_amount": 300, "comment": null, "conversion": { "id": 2 }, "payout": null, "affiliate": { "id": "janejameson", "firstname": "Jane", "lastname": "Jameson" }, "kind": "regular", "currency": "EUR", "final": null, "finalization_date": null, "commission_name": "standard" }, { "id": 1, "amount": 55, "approved": true, "created_at": "2021-03-31T08:21:02+0000", "commission_type": "standard", "conversion_sub_amount": 550, "comment": null, "conversion": { "id": 1 }, "payout": null, "affiliate": { "id": "janejameson", "firstname": "Jane", "lastname": "Jameson" }, "kind": "regular", "currency": "USD", "final": null, "finalization_date": null, "commission_name": "standard" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "summary": "List all commissions", "operationId": "listAllCommissions", "tags": [ "Commissions" ], "parameters": [ { "name": "affiliate_id", "in": "query", "description": "The affiliate Id", "example": "janejameson", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "An optional approval status to filter by. Valid values are: `approved` | `disapproved` | `pending`", "example": "approved", "schema": { "type": "string" } }, { "name": "paid", "in": "query", "description": "Only show commissions that are paid out. Valid values are: `1` | `0`", "example": "0", "schema": { "type": "boolean" } } ] } }, "/commissions/{commission_id}/approved/": { "put": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommissionModel" }, "example": { "id": 1, "conversion_sub_amount": 550, "amount": 55, "commission_type": "standard", "approved": true, "affiliate": { "id": "janejameson", "firstname": "Jane", "lastname": "Jameson" }, "conversion": { "id": 1 }, "kind": "regular", "currency": "USD", "created_at": null, "payout": null, "comment": null, "final": null, "finalization_date": null, "commission_name": "standard" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Approve a commission", "operationId": "approveACommission", "tags": [ "Commissions" ], "parameters": [ { "name": "commission_id", "in": "path", "description": "Numeric `id` of the commission to perform action with.", "required": true, "example": "1", "schema": { "type": "number" } } ], "x-mint": { "metadata": { "playground": "simple" } } }, "delete": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number" }, "conversion_sub_amount": { "type": "number" }, "amount": { "type": "number" }, "commission_type": { "type": "string" }, "approved": { "type": "boolean" }, "affiliate": { "type": "object", "properties": { "id": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" } } }, "conversion": { "type": "object", "properties": { "id": { "type": "number" } } }, "kind": { "type": "string" }, "currency": { "type": "string" }, "created_at": { "nullable": true }, "payout": { "nullable": true }, "comment": { "nullable": true }, "final": { "nullable": true }, "finalization_date": { "nullable": true }, "commission_name": { "type": "string" } } }, "example": { "id": 1, "conversion_sub_amount": 550, "amount": 55, "commission_type": "standard", "approved": false, "affiliate": { "id": "janejameson", "firstname": "Jane", "lastname": "Jameson" }, "conversion": { "id": 1 }, "kind": "regular", "currency": "USD", "created_at": null, "payout": null, "comment": null, "final": null, "finalization_date": null, "commission_name": "standard" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Disapprove a commission", "operationId": "disapproveACommission", "tags": [ "Commissions" ], "parameters": [ { "name": "commission_id", "in": "path", "description": "Numeric `id` of the commission to perform action with.", "required": true, "example": "1", "schema": { "type": "number" } } ], "x-mint": { "metadata": { "playground": "simple" } } } }, "/affiliates/{affiliate_id}/": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AffiliateModel" }, "example": { "id": "janejameson", "firstname": "Jane", "lastname": "Jameson", "email": "jane@example-blog.inc", "company": { "name": "Example blog Inc.", "description": "Best blog ever" }, "address": { "address": "Rapenburgerstraat 173", "address_two": null, "postal_code": "1011 VM", "city": "Amsterdam", "state": "Noord-Holland", "country": { "code": "NL", "name": "Netherlands" } }, "meta_data": { "foo": "bar", "meta": "data" }, "parent_id": "sandrasanderson", "affiliate_group_id": null, "created_at": "2021-03-03T12:39:19+0000", "promoted_at": null, "promotion_method": null, "custom_fields": { "field1": "value1" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Retrieve an affiliate", "operationId": "retrieveAnAffiliate", "tags": [ "Affiliates" ], "parameters": [ { "name": "affiliate_id", "in": "path", "description": "The `id` of the affiliate.", "required": true, "example": "janejameson", "schema": { "type": "string" } } ] }, "delete": { "responses": { "204": { "description": "No Content", "headers": {}, "content": {} }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Delete an affiliate", "operationId": "deleteAnAffiliate", "tags": [ "Affiliates" ], "parameters": [ { "name": "affiliate_id", "in": "path", "description": "The `id` of the affiliate.", "required": true, "example": "janejameson", "schema": { "type": "string" } } ], "x-mint": { "metadata": { "playground": "simple" } } } }, "/affiliates/": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" }, "email": { "type": "string" }, "company": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } }, "address": { "type": "object", "properties": { "address": { "type": "string" }, "address_two": { "nullable": true }, "postal_code": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } } } }, "meta_data": { "type": "object", "properties": { "foo": { "type": "string" }, "meta": { "type": "string" } } }, "parent_id": { "type": "string" }, "created_at": { "nullable": true }, "affiliate_group_id": { "nullable": true }, "promoted_at": { "nullable": true }, "promotion_method": { "nullable": true }, "custom_fields": { "type": "object", "properties": { "field1": { "type": "string" } } } } } }, "example": [ { "id": "janejameson", "firstname": "Jane", "lastname": "Jameson", "email": "jane@example-blog.inc", "company": { "name": "Example blog Inc.", "description": "Best blog ever" }, "address": { "address": "Rapenburgerstraat 173", "address_two": null, "postal_code": "1011 VM", "city": "Amsterdam", "state": "Noord-Holland", "country": { "code": "NL", "name": "Netherlands" } }, "meta_data": { "foo": "bar", "meta": "data" }, "parent_id": "sandrasanderson", "created_at": null, "affiliate_group_id": null, "promoted_at": null, "promotion_method": null, "custom_fields": { "field1": "value1" } } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "summary": "List all affiliates", "operationId": "listAllAffiliates", "tags": [ "Affiliates" ], "parameters": [ { "name": "click_id", "in": "query", "description": "A click id", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "schema": { "type": "string" } }, { "name": "source_id", "in": "query", "description": "A source id", "example": "1-ssssss", "schema": { "type": "string" } }, { "name": "email", "in": "query", "description": "An email address", "example": "jane@example-blog.inc", "schema": { "type": "string" } }, { "name": "referral_code", "in": "query", "description": "An affiliate's referral code. This corresponds to the value of `ref=` in their referral link.", "example": "nwjinmy", "schema": { "type": "string" } }, { "name": "parent_id", "in": "query", "description": "Retrieves children for a certain parent affiliate", "example": "sandrasanderson", "schema": { "type": "string" } }, { "name": "affiliate_group_id", "in": "query", "description": "Retrieves affiliates for a certain affiliate group", "example": "ag_eXampl3", "schema": { "type": "string" } } ] }, "post": { "responses": { "200": { "description": "OK", "headers": {}, "content": {} }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "summary": "Create an affiliate", "operationId": "createAnAffiliate", "tags": [ "Affiliates" ], "requestBody": { "content": { "application/json": { "example": { "firstname": "Ramone", "lastname": "Referra", "email": "ramona@referra.com", "password": "password1234", "company": { "name": "Referra Inc.", "description": "Best referrer ever" }, "address": { "address": "Rapenburgerstraat 173", "address_two": null, "postal_code": "1011 VM", "city": "Amsterdam", "state": "Noord-Holland", "country": { "code": "NL" } }, "custom_fields": { "field1": "value1" } }, "schema": { "type": "object", "properties": {} } } } }, "x-mint": { "metadata": { "playground": "simple" } } } }, "/affiliates/{affiliate_id}/group/": { "put": { "responses": { "200": { "description": "OK", "headers": {}, "content": {} }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Set affiliate group", "operationId": "setAffiliateGroup", "tags": [ "Affiliates" ], "parameters": [ { "name": "affiliate_id", "in": "path", "description": "The `id` of the affiliate.", "required": true, "example": "janejameson", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "group_id": "ag_eXampl3" }, "schema": { "type": "object", "properties": { "group_id": { "type": "string" } } } } } }, "x-mint": { "metadata": { "playground": "simple" } } }, "delete": { "responses": { "204": { "description": "No Content", "headers": {}, "content": {} }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Remove affiliate group", "operationId": "removeAffiliateGroup", "tags": [ "Affiliates" ], "parameters": [ { "name": "affiliate_id", "in": "path", "description": "The `id` of the affiliate.", "required": true, "example": "janejameson", "schema": { "type": "string" } } ], "x-mint": { "metadata": { "playground": "simple" } } } }, "/affiliates/{affiliate_id}/notes/{id}/": { "put": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number" }, "created_at": { "type": "string" }, "message": { "type": "string" }, "created_by": { "type": "object", "properties": { "id": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" } } } } }, "example": { "id": 1, "created_at": "2021-09-12T13:34:18+0000", "message": "Greatest person ever!", "created_by": { "id": "johntapper", "firstname": "John", "lastname": "Tapper" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Update note", "operationId": "updateNote", "tags": [ "Affiliates" ], "parameters": [ { "name": "affiliate_id", "in": "path", "description": "The `id` of the affiliate.", "required": true, "example": "janejameson", "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "The `id` of the note.", "required": true, "example": "1", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "message": "Greatest person ever!" }, "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Greatest person ever!", "description": "The content of the note" } } } } } }, "x-mint": { "metadata": { "playground": "simple" } } }, "delete": { "responses": { "204": { "description": "No Content", "headers": {}, "content": {} }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Delete note", "operationId": "deleteNote", "tags": [ "Affiliates" ], "parameters": [ { "name": "affiliate_id", "in": "path", "description": "The `id` of the affiliate.", "required": true, "example": "janejameson", "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "The `id` of the note.", "required": true, "example": "1", "schema": { "type": "string" } } ], "x-mint": { "metadata": { "playground": "simple" } } } }, "/affiliates/{affiliate_id}/notes/": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "created_at": { "type": "string" }, "message": { "type": "string" }, "created_by": { "type": "object", "properties": { "id": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" } } } } } }, "example": [ { "id": 1, "created_at": "2021-09-12T13:34:18+0000", "message": "Great person!", "created_by": { "id": "johntapper", "firstname": "John", "lastname": "Tapper" } } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "List notes", "operationId": "listNotes", "tags": [ "Affiliates" ], "parameters": [ { "name": "affiliate_id", "in": "path", "description": "The `id` of the affiliate.", "required": true, "example": "janejameson", "schema": { "type": "string" } } ] }, "post": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "number" }, "created_at": { "type": "string" }, "message": { "type": "string" }, "created_by": { "type": "object", "properties": { "id": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" } } } } }, "example": { "id": 1, "created_at": "2021-09-12T13:34:18+0000", "message": "Great person!", "created_by": { "id": "johntapper", "firstname": "John", "lastname": "Tapper" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Create note", "operationId": "createNote", "tags": [ "Affiliates" ], "parameters": [ { "name": "affiliate_id", "in": "path", "description": "The `id` of the affiliate.", "required": true, "example": "janejameson", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "message": "Great person!" }, "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Great person!", "description": "The content of the note" } } } } } }, "x-mint": { "metadata": { "playground": "simple" } } } }, "/affiliates/{affiliate_id}/meta-data/": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "foo": { "type": "string" }, "meta": { "type": "string" } } }, "example": { "foo": "bar", "meta": "data" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Retrieve meta data", "operationId": "retrieveMetaData22", "tags": [ "Affiliates" ], "parameters": [ { "name": "affiliate_id", "in": "path", "description": "The `id` of the affiliate.", "required": true, "example": "janejameson", "schema": { "type": "string" } } ] }, "put": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "foo": { "type": "string" }, "baz": { "type": "string" } } }, "example": { "foo": "bar", "baz": "qux" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Update (replace) meta data", "operationId": "updateReplaceMetaData22", "tags": [ "Affiliates" ], "parameters": [ { "name": "affiliate_id", "in": "path", "description": "The `id` of the affiliate.", "required": true, "example": "janejameson", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "foo": "bar", "baz": "qux" }, "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "example": "value", "description": "A key value pair. Multiple allowed" } } } } } }, "x-mint": { "metadata": { "playground": "simple" } } } }, "/affiliates/{affiliate_id}/meta-data/{key}/": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string" } } }, "example": { "value": "bar" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Retrieve meta data by key", "operationId": "retrieveMetaDataByKey22", "tags": [ "Affiliates" ], "parameters": [ { "name": "affiliate_id", "in": "path", "description": "The `id` of the affiliate.", "required": true, "example": "janejameson", "schema": { "type": "string" } }, { "name": "key", "in": "path", "description": "The meta data `key`.", "required": true, "example": "foo", "schema": { "type": "string" } } ] }, "put": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string" } } }, "example": { "value": "My value" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Set meta data by key", "operationId": "setMetaDataByKey22", "tags": [ "Affiliates" ], "parameters": [ { "name": "affiliate_id", "in": "path", "description": "The `id` of the affiliate.", "required": true, "example": "janejameson", "schema": { "type": "string" } }, { "name": "key", "in": "path", "description": "The meta data `key`.", "required": true, "example": "foo", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "value": "My value" }, "schema": { "type": "object", "required": [ "value" ], "properties": { "value": { "type": "string", "example": "Bar", "description": "The value to set for the given key" } } } } } }, "x-mint": { "metadata": { "playground": "simple" } } }, "delete": { "responses": { "204": { "description": "No Content", "headers": {}, "content": {} }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Delete meta data by key", "operationId": "deleteMetaDataByKey22", "tags": [ "Affiliates" ], "parameters": [ { "name": "affiliate_id", "in": "path", "description": "The `id` of the affiliate.", "required": true, "example": "janejameson", "schema": { "type": "string" } }, { "name": "key", "in": "path", "description": "The meta data `key`.", "required": true, "example": "foo", "schema": { "type": "string" } } ], "x-mint": { "metadata": { "playground": "simple" } } } }, "/affiliates/{affiliate_id}/payout-methods/{payout_method_id}/": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "id": { "type": "string" }, "details": { "type": "object", "properties": { "paypal_address": { "type": "string" } } }, "primary": { "type": "boolean" } } }, "example": { "title": "Paypal", "id": "paypal", "details": { "paypal_address": "jane@example-blog.inc" }, "primary": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Get payout method", "operationId": "getPayoutMethod", "tags": [ "Affiliates" ], "parameters": [ { "name": "affiliate_id", "in": "path", "description": "The `id` of the affiliate", "required": true, "example": "janejameson", "schema": { "type": "string" } }, { "name": "payout_method_id", "in": "path", "description": "The `id` of the payout method", "required": true, "example": "paypal", "schema": { "type": "string" } } ] }, "put": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "id": { "type": "string" }, "details": { "type": "object", "properties": { "paypal_address": { "type": "string" } } }, "primary": { "type": "boolean" } } }, "example": { "title": "Paypal", "id": "paypal", "details": { "paypal_address": "jane@example-blog.inc" }, "primary": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Set payout method", "operationId": "setPayoutMethod", "description": "The body of the request should contain the appropriate data for the payout method you are setting. The field ids can be found by exporting payouts as .csv on the payouts page.", "tags": [ "Affiliates" ], "parameters": [ { "name": "affiliate_id", "in": "path", "description": "The `id` of the affiliate", "required": true, "example": "janejameson", "schema": { "type": "string" } }, { "name": "payout_method_id", "in": "path", "description": "The `id` of the payout method", "required": true, "example": "paypal", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "paypal_address": "jane@example-blog.inc" }, "schema": { "type": "object", "properties": { "paypal_address": { "type": "string" } } } } } }, "x-mint": { "metadata": { "playground": "simple" } } } }, "/affiliates/{affiliate_id}/payout-methods/": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "id": { "type": "string" }, "details": { "type": "object", "properties": { "paypal_address": { "type": "string" } } }, "primary": { "type": "boolean" } } } }, "example": [ { "title": "Paypal", "id": "paypal", "details": { "paypal_address": "jane@example-blog.inc" }, "primary": true } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "List payout methods", "operationId": "listPayoutMethods", "tags": [ "Affiliates" ], "parameters": [ { "name": "affiliate_id", "in": "path", "description": "The `id` of the affiliate", "required": true, "example": "janejameson", "schema": { "type": "string" } } ] } }, "/affiliates/{child_affiliate_id}/parent/": { "post": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" }, "email": { "type": "string" }, "company": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } }, "address": { "type": "object", "properties": { "address": { "type": "string" }, "address_two": { "nullable": true }, "postal_code": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } } } }, "meta_data": { "type": "object", "properties": { "foo": { "type": "string" }, "meta": { "type": "string" } } }, "parent_id": { "type": "string" }, "created_at": { "type": "string" }, "affiliate_group_id": { "nullable": true }, "promoted_at": { "nullable": true }, "promotion_method": { "nullable": true }, "custom_fields": { "type": "object", "properties": { "field1": { "type": "string" } } } } }, "example": { "id": "janejameson", "firstname": "Jane", "lastname": "Jameson", "email": "jane@example-blog.inc", "company": { "name": "Example blog Inc.", "description": "Best blog ever" }, "address": { "address": "Rapenburgerstraat 173", "address_two": null, "postal_code": "1011 VM", "city": "Amsterdam", "state": "Noord-Holland", "country": { "code": "NL", "name": "Netherlands" } }, "meta_data": { "foo": "bar", "meta": "data" }, "parent_id": "sandrasanderson", "created_at": "2021-03-03T12:39:19+0100", "affiliate_group_id": null, "promoted_at": null, "promotion_method": null, "custom_fields": { "field1": "value1" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Set parent", "operationId": "setParent", "tags": [ "Affiliates" ], "parameters": [ { "name": "child_affiliate_id", "in": "path", "description": "The `id` of the affiliate whoms parent is being set.", "required": true, "example": "janejameson", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example1": { "value": { "affiliate_id": "sandrasanderson" } }, "example2": { "value": { "via": "3" } } }, "schema": { "oneOf": [ { "type": "object", "properties": { "affiliate_id": { "type": "string", "example": "sandrasanderson", "description": "The letter `id` of the parent affiliate" } } }, { "type": "object", "properties": { "via": { "type": "string", "example": "3", "description": "The numeral `id` of the parent affiliate" } } } ] } } } }, "x-mint": { "metadata": { "playground": "simple" } } }, "delete": { "responses": { "204": { "description": "No Content", "headers": {}, "content": {} }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Remove parent", "operationId": "removeParent", "tags": [ "Affiliates" ], "parameters": [ { "name": "child_affiliate_id", "in": "path", "description": "The `id` of the affiliate whoms parent is being set.", "required": true, "example": "janejameson", "schema": { "type": "string" } } ], "x-mint": { "metadata": { "playground": "simple" } } } }, "/affiliates/{affiliate_id}/balances/": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "USD": { "type": "number" }, "EUR": { "type": "number" } } }, "example": { "USD": 5, "EUR": 35 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Retrieve affiliate's balances", "operationId": "retrieveAffiliateSBalances", "tags": [ "Affiliates" ], "parameters": [ { "name": "affiliate_id", "in": "path", "description": "The `id` of the affiliate whoms balances to retrieve.", "required": true, "example": "janejameson", "schema": { "type": "string" } } ] } }, "/affiliates/{affiliate_id}/payments/": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string" }, "affiliate": { "type": "object", "properties": { "id": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" } } }, "amount": { "type": "number" }, "currency": { "type": "string" } } } }, "example": [ { "id": "pa_eXampl3", "created_at": "2021-03-29T08:36:07+00:00", "affiliate": { "id": "janejameson", "firstname": "Jane", "lastname": "Jameson" }, "amount": 50, "currency": "USD" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "List affiliate's payments", "operationId": "listAffiliateSPayments", "tags": [ "Affiliates" ], "parameters": [ { "name": "affiliate_id", "in": "path", "description": "The `id` of the affiliate whoms payments to list.", "required": true, "example": "janejameson", "schema": { "type": "string" } } ] } }, "/affiliates/{id}/programs/": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "applied_at": { "type": "string" }, "approved": { "type": "boolean" }, "coupon": { "type": "string" }, "id": { "type": "string" }, "referral_link": { "type": "object", "properties": { "asset_id": { "type": "string" }, "link": { "type": "string" }, "source_id": { "type": "string" } } }, "title": { "type": "string" }, "assets_amount": { "type": "number" } } } }, "example": [ { "applied_at": "2021-07-06T12:25:21+00:00", "approved": true, "coupon": "JANE10OFF", "id": "johns-affiliate-program", "referral_link": { "asset_id": "1-aaaaaa", "link": "https://tapper.inc/johns-cool-product/?ref=nwjinmy", "source_id": "1-ssssss" }, "title": "John's affiliate program", "assets_amount": 2 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Get affiliations", "operationId": "getAffiliations", "tags": [ "Affiliates" ], "parameters": [ { "name": "id", "in": "path", "description": "The `id` of the affiliate.", "required": true, "example": "u_JaN3-J0n", "schema": { "type": "string" } } ] } }, "/affiliates/custom-fields/": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "choices": { "type": "array", "items": {} } } } }, "example": [ { "id": "field1", "title": "field1", "choices": [] } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "summary": "Get custom fields", "operationId": "getCustomFields", "tags": [ "Affiliates" ] } }, "/affiliate-groups/": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "affiliate_count": { "type": "number" } } } }, "example": [ { "id": "ag_eXampl3", "title": "Gold affiliates", "affiliate_count": 0 } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "summary": "List all affiliate groups", "operationId": "listAllAffiliateGroups", "tags": [ "Affiliate Groups" ] }, "post": { "responses": { "200": { "description": "OK", "headers": {}, "content": {} }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "summary": "Create new affiliate group", "operationId": "createNewAffiliateGroup", "tags": [ "Affiliate Groups" ], "requestBody": { "content": { "application/json": { "example": { "title": "Silver Affiliates" }, "schema": { "type": "object", "properties": { "title": { "type": "string" } } } } } }, "x-mint": { "metadata": { "playground": "simple" } } } }, "/affiliate-groups/{affiliate_group_id}/": { "patch": { "responses": { "200": { "description": "OK", "headers": {}, "content": {} }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Update affiliate group", "operationId": "updateAffiliateGroup", "tags": [ "Affiliate Groups" ], "parameters": [ { "name": "affiliate_group_id", "in": "path", "description": "Retrieves affiliates for a certain affiliate group", "example": "ag_eXampl3", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "example": { "title": "Gold members" }, "schema": { "type": "object", "properties": { "title": { "type": "string" } } } } } }, "x-mint": { "metadata": { "playground": "simple" } } } }, "/affiliate-prospects/": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" }, "email": { "type": "string" }, "company": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } }, "address": { "type": "object", "properties": { "address": { "type": "string" }, "address_two": { "nullable": true }, "postal_code": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } } } }, "signup_source": { "type": "string" }, "referral_link": { "type": "object", "properties": { "link": { "type": "string" }, "asset_id": { "type": "string" }, "source_id": { "type": "string" } } }, "created_at": { "type": "string" }, "promoted_at": { "nullable": true }, "promotion_method": { "nullable": true } } } }, "example": [ { "id": "peterpeterson", "firstname": "Peter", "lastname": "Peterson", "email": "peter@example-existing-customer.inc", "company": { "name": "Example prospect Inc.", "description": "Great affiliate prospect" }, "address": { "address": "1 Holywood Drive", "address_two": null, "postal_code": "90210", "city": "Los Angeles", "state": "CA", "country": { "code": "US", "name": "United States" } }, "signup_source": "stripe-integration", "referral_link": { "link": "https://tapper.inc/johns-cool-product/?ref=yza5njg", "asset_id": "1-aaaaaa", "source_id": "3-rrrrrr" }, "created_at": "2021-05-27T11:39:03+00:00", "promoted_at": null, "promotion_method": null } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "summary": "List all affiliate prospects", "operationId": "listAllAffiliateProspects", "tags": [ "Affiliate Prospects" ], "parameters": [ { "name": "email", "in": "query", "description": "An email address", "example": "peter@example-existing-customer.inc", "schema": { "type": "string" } }, { "name": "referral_code", "in": "query", "description": "An affiliate prospect's referral code. This corresponds to the value of `ref=` in their referral link.", "example": "yza5njg", "schema": { "type": "string" } }, { "name": "program_id", "in": "query", "description": "Retrieves affiliate prospects for a certain program", "example": "johns-affiliate-program", "schema": { "type": "string" } }, { "name": "group_id", "in": "query", "description": "Retrieves affiliate prospects for a certain affiliate group", "schema": { "type": "string" } } ] }, "post": { "responses": { "200": { "description": "OK", "headers": {}, "content": {} }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "summary": "Create an affiliate prospect", "operationId": "createAnAffiliateProspect", "tags": [ "Affiliate Prospects" ], "requestBody": { "content": { "application/json": { "example": { "firstname": "Jim", "lastname": "Prosper", "email": "jim@prosper.inc", "company": { "name": "Prosper Inc.", "description": "Live long and.." }, "address": { "address": "41153.7 Star avenue", "address_two": null, "postal_code": "1011 VM", "city": "Nebula 5", "state": "Milky Way", "country": { "code": "US", "name": "United States" } } }, "schema": { "type": "object", "properties": {} } } } }, "x-mint": { "metadata": { "playground": "simple" } } } }, "/affiliate-prospects/{affiliate_prospect_id}/": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AffiliateProspectModel" }, "example": { "id": "peterpeterson", "firstname": "Peter", "lastname": "Peterson", "email": "peter@example-existing-customer.inc", "company": { "name": "Example prospect Inc.", "description": "Great affiliate prospect" }, "address": { "address": "1 Holywood Drive", "address_two": null, "postal_code": "90210", "city": "Los Angeles", "state": "CA", "country": { "code": "US", "name": "United States" } }, "signup_source": "stripe-integration", "referral_link": { "link": "https://tapper.inc/johns-cool-product/?ref=yza5njg", "asset_id": "1-aaaaaa", "source_id": "3-rrrrrr" }, "created_at": "2021-05-27T11:39:03+00:00", "promoted_at": null, "promotion_method": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Retrieve an affiliate prospect", "operationId": "retrieveAnAffiliateProspect", "tags": [ "Affiliate Prospects" ], "parameters": [ { "name": "affiliate_prospect_id", "in": "path", "description": "The `id` of the affiliate prospect.", "required": true, "example": "peterpeterson", "schema": { "type": "string" } } ] }, "delete": { "responses": { "204": { "description": "No Content", "headers": {}, "content": {} }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Delete an affiliate prospect", "operationId": "deleteAnAffiliateProspect", "tags": [ "Affiliate Prospects" ], "parameters": [ { "name": "affiliate_prospect_id", "in": "path", "description": "The `id` of the affiliate prospect.", "required": true, "example": "peterpeterson", "schema": { "type": "string" } } ], "x-mint": { "metadata": { "playground": "simple" } } } }, "/programs/{program_id}/": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": {} }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Retrieve a program", "operationId": "retrieveAProgram", "tags": [ "Programs" ], "parameters": [ { "name": "program_id", "in": "path", "description": "The `id` of the Program. This id can be found as part of the url when viewing the program on the platform.", "required": true, "example": "johns-affiliate-program", "schema": { "type": "string" } } ] } }, "/programs/": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "currency": { "type": "string" }, "title": { "type": "string" }, "cookie_time": { "type": "number" }, "default_landing_page_url": { "type": "string" }, "recurring": { "type": "boolean" }, "recurring_cap": { "nullable": true }, "recurring_period_days": { "nullable": true }, "program_category": { "type": "object", "properties": { "id": { "type": "number" }, "identifier": { "type": "string" }, "title": { "type": "string" }, "is_admitad_suitable": { "type": "boolean" } } }, "currency_symbol": { "type": "string" }, "contact_email": { "nullable": true }, "status": { "type": "string" } } } }, "example": [ { "id": "johns-affiliate-program", "currency": "USD", "title": "John's affiliate program", "cookie_time": 45, "default_landing_page_url": "https://tapper.inc/johns-cool-product/", "recurring": true, "recurring_cap": null, "recurring_period_days": null, "program_category": { "id": 1, "identifier": "admitad_test", "title": "Parent category", "is_admitad_suitable": false }, "currency_symbol": "$", "contact_email": null, "status": "active" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "summary": "List all programs", "operationId": "listAllPrograms", "tags": [ "Programs" ], "parameters": [ { "name": "asset_id", "in": "query", "description": "An asset id", "example": "1-aaaaaa", "schema": { "type": "string" } } ] } }, "/programs/{program_id}/affiliates/": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" }, "email": { "type": "string" }, "company": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } }, "address": { "type": "object", "properties": { "address": { "type": "string" }, "address_two": { "nullable": true }, "postal_code": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } } } }, "meta_data": { "type": "object", "properties": { "foo": { "type": "string" }, "meta": { "type": "string" } } }, "parent_id": { "type": "string" }, "referral_link": { "type": "object", "properties": { "link": { "type": "string" }, "asset_id": { "type": "string" }, "source_id": { "type": "string" } } }, "coupon": { "type": "string" }, "approved": { "type": "boolean" }, "affiliate_group_id": { "nullable": true }, "created_at": { "nullable": true }, "applied_at": { "type": "string" }, "promoted_at": { "nullable": true }, "promotion_method": { "nullable": true }, "custom_fields": { "type": "object", "properties": { "field1": { "type": "string" } } } } } }, "example": [ { "id": "janejameson", "firstname": "Jane", "lastname": "Jameson", "email": "jane@example-blog.inc", "company": { "name": "Example blog Inc.", "description": "Best blog ever" }, "address": { "address": "Rapenburgerstraat 173", "address_two": null, "postal_code": "1011 VM", "city": "Amsterdam", "state": "Noord-Holland", "country": { "code": "NL", "name": "Netherlands" } }, "meta_data": { "foo": "bar", "meta": "data" }, "parent_id": "sandrasanderson", "referral_link": { "link": "https://tapper.inc/johns-cool-product/?ref=nwjinmy", "asset_id": "1-aaaaaa", "source_id": "1-ssssss" }, "coupon": "JANE10OFF", "approved": true, "affiliate_group_id": null, "created_at": null, "applied_at": "2021-05-27T11:39:03+00:00", "promoted_at": null, "promotion_method": null, "custom_fields": { "field1": "value1" } } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "List all affiliates in program", "operationId": "listAllAffiliatesInProgram", "tags": [ "Programs" ], "parameters": [ { "name": "program_id", "in": "path", "description": "The `id` of the Program to add the affiliate too. This id can be found as part of the url when viewing the program on the platform.", "required": true, "example": "johns-affiliate-program", "schema": { "type": "string" } }, { "name": "source_id", "in": "query", "description": "A source id", "example": "1-ssssss", "schema": { "type": "string" } }, { "name": "email", "in": "query", "description": "An email address", "example": "jane@example-blog.inc", "schema": { "type": "string" } }, { "name": "parent_id", "in": "query", "description": "Retrieves children for a certain parent affiliate", "example": "sandrasanderson", "schema": { "type": "string" } }, { "name": "affiliate_group_id", "in": "query", "description": "Retrieves affiliates for a certain affiliate group", "example": "ag_eXampl3", "schema": { "type": "string" } } ] }, "post": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" }, "email": { "type": "string" }, "company": { "nullable": true }, "address": { "nullable": true }, "meta_data": { "type": "object", "properties": {} }, "parent_id": { "nullable": true }, "referral_link": { "type": "object", "properties": { "link": { "type": "string" }, "asset_id": { "type": "string" }, "source_id": { "nullable": true } } }, "coupon": { "type": "string" }, "approved": { "nullable": true }, "created_at": { "nullable": true }, "affiliate_group_id": { "nullable": true }, "applied_at": { "type": "string" }, "promoted_at": { "nullable": true }, "promotion_method": { "nullable": true }, "custom_fields": { "nullable": true } } }, "example": { "id": "sandrasanderson", "firstname": "Mike", "lastname": "Mikerson", "email": "mike@example-parent.inc", "company": null, "address": null, "meta_data": {}, "parent_id": null, "referral_link": { "link": "https://tapper.inc/johns-cool-product/?ref=ztdkzgf", "asset_id": "1-aaaaaa", "source_id": null }, "coupon": "MIKEFREESHIPPING", "approved": null, "created_at": null, "affiliate_group_id": null, "applied_at": "2021-05-27T11:30:38+00:00", "promoted_at": null, "promotion_method": null, "custom_fields": null } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Add an affiliate to a program", "operationId": "addAnAffiliateToAProgram", "tags": [ "Programs" ], "parameters": [ { "name": "program_id", "in": "path", "description": "The `id` of the Program to add the affiliate too. This id can be found as part of the url when viewing the program on the platform.", "required": true, "example": "johns-affiliate-program", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "affiliate_id": "mikemikerson", "approved": null, "coupon": "MIKEFREESHIPPING" }, "schema": { "$ref": "#/components/schemas/AddAffiliateToProgram" } } } }, "x-mint": { "metadata": { "playground": "simple" } } } }, "/programs/{program_id}/affiliates/{affiliate_id}/": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" }, "email": { "type": "string" }, "company": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } }, "address": { "type": "object", "properties": { "address": { "type": "string" }, "address_two": { "nullable": true }, "postal_code": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } } } }, "meta_data": { "type": "object", "properties": { "foo": { "type": "string" }, "meta": { "type": "string" } } }, "parent_id": { "type": "string" }, "referral_link": { "type": "object", "properties": { "link": { "type": "string" }, "asset_id": { "type": "string" }, "source_id": { "type": "string" } } }, "coupon": { "type": "string" }, "approved": { "type": "boolean" }, "affiliate_group_id": { "nullable": true }, "created_at": { "type": "string" }, "applied_at": { "type": "string" }, "promoted_at": { "nullable": true }, "promotion_method": { "nullable": true }, "custom_fields": { "type": "object", "properties": { "field1": { "type": "string" } } } } }, "example": { "id": "janejameson", "firstname": "Jane", "lastname": "Jameson", "email": "jane@example-blog.inc", "company": { "name": "Example blog Inc.", "description": "Best blog ever" }, "address": { "address": "Rapenburgerstraat 173", "address_two": null, "postal_code": "1011 VM", "city": "Amsterdam", "state": "Noord-Holland", "country": { "code": "NL", "name": "Netherlands" } }, "meta_data": { "foo": "bar", "meta": "data" }, "parent_id": "sandrasanderson", "referral_link": { "link": "https://tapper.inc/johns-cool-product/?ref=nwjinmy", "asset_id": "1-aaaaaa", "source_id": "1-ssssss" }, "coupon": "JANE10OFF", "approved": true, "affiliate_group_id": null, "created_at": "2021-05-27T11:39:03+00:00", "applied_at": "2021-05-27T11:39:03+00:00", "promoted_at": null, "promotion_method": null, "custom_fields": { "field1": "value1" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Retrieve an affiliate in a program", "operationId": "retrieveAnAffiliateInAProgram", "tags": [ "Programs" ], "parameters": [ { "name": "program_id", "in": "path", "description": "The `id` of the Program.", "required": true, "example": "johns-affiliate-program", "schema": { "type": "string" } }, { "name": "affiliate_id", "in": "path", "description": "The `id` of the affiliate.", "required": true, "example": "janejameson", "schema": { "type": "string" } } ] }, "patch": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" }, "email": { "type": "string" }, "company": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } }, "address": { "type": "object", "properties": { "address": { "type": "string" }, "address_two": { "nullable": true }, "postal_code": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } } } }, "meta_data": { "type": "object", "properties": { "foo": { "type": "string" }, "meta": { "type": "string" } } }, "parent_id": { "type": "string" }, "referral_link": { "type": "object", "properties": { "link": { "type": "string" }, "asset_id": { "type": "string" }, "source_id": { "type": "string" } } }, "coupon": { "type": "string" }, "approved": { "type": "boolean" }, "affiliate_group_id": { "nullable": true }, "created_at": { "type": "string" }, "applied_at": { "type": "string" }, "promoted_at": { "nullable": true }, "promotion_method": { "nullable": true }, "custom_fields": { "type": "object", "properties": { "field1": { "type": "string" } } } } }, "example": { "id": "janejameson", "firstname": "Jane", "lastname": "Jameson", "email": "jane@example-blog.inc", "company": { "name": "Example blog Inc.", "description": "Best blog ever" }, "address": { "address": "Rapenburgerstraat 173", "address_two": null, "postal_code": "1011 VM", "city": "Amsterdam", "state": "Noord-Holland", "country": { "code": "NL", "name": "Netherlands" } }, "meta_data": { "foo": "bar", "meta": "data" }, "parent_id": "sandrasanderson", "referral_link": { "link": "https://tapper.inc/johns-cool-product/?ref=nwjinmy", "asset_id": "1-aaaaaa", "source_id": "1-ssssss" }, "coupon": "JANE20OFF", "approved": true, "affiliate_group_id": null, "created_at": "2021-05-27T11:39:03+00:00", "applied_at": "2021-05-27T11:39:03+00:00", "promoted_at": null, "promotion_method": null, "custom_fields": { "field1": "value1" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Update an affiliate in a program", "operationId": "updateAnAffiliateInAProgram", "tags": [ "Programs" ], "parameters": [ { "name": "program_id", "in": "path", "description": "The `id` of the Program.", "required": true, "example": "johns-affiliate-program", "schema": { "type": "string" } }, { "name": "affiliate_id", "in": "path", "description": "The `id` of the affiliate.", "required": true, "example": "janejameson", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "coupon": "JANE20OFF" }, "schema": { "type": "object", "required": [ "coupon" ], "properties": { "coupon": { "type": "string", "example": "JANE20OFF", "description": "The affiliate's coupon code for this program" } } } } } }, "x-mint": { "metadata": { "playground": "simple" } } } }, "/programs/{program_id}/affiliates/{affiliate_id}/approved/": { "put": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" }, "email": { "type": "string" }, "company": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } }, "address": { "type": "object", "properties": { "address": { "type": "string" }, "address_two": { "nullable": true }, "postal_code": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } } } }, "meta_data": { "type": "object", "properties": { "foo": { "type": "string" }, "meta": { "type": "string" } } }, "parent_id": { "type": "string" }, "referral_link": { "type": "object", "properties": { "link": { "type": "string" }, "asset_id": { "type": "string" }, "source_id": { "type": "string" } } }, "coupon": { "type": "string" }, "approved": { "type": "boolean" }, "affiliate_group_id": { "nullable": true }, "created_at": { "type": "string" }, "applied_at": { "type": "string" }, "promoted_at": { "nullable": true }, "promotion_method": { "nullable": true }, "custom_fields": { "type": "object", "properties": { "field1": { "type": "string" } } } } }, "example": { "id": "janejameson", "firstname": "Jane", "lastname": "Jameson", "email": "jane@example-blog.inc", "company": { "name": "Example blog Inc.", "description": "Best blog ever" }, "address": { "address": "Rapenburgerstraat 173", "address_two": null, "postal_code": "1011 VM", "city": "Amsterdam", "state": "Noord-Holland", "country": { "code": "NL", "name": "Netherlands" } }, "meta_data": { "foo": "bar", "meta": "data" }, "parent_id": "sandrasanderson", "referral_link": { "link": "https://tapper.inc/johns-cool-product/?ref=nwjinmy", "asset_id": "1-aaaaaa", "source_id": "1-ssssss" }, "coupon": "JANE10OFF", "approved": true, "affiliate_group_id": null, "created_at": "2021-05-27T11:39:03+00:00", "applied_at": "2021-05-27T11:39:03+00:00", "promoted_at": null, "promotion_method": null, "custom_fields": { "field1": "value1" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Approve an affiliate", "operationId": "approveAnAffiliate", "tags": [ "Programs" ], "parameters": [ { "name": "program_id", "in": "path", "description": "The `id` of the program to add the affiliate too. This id can be found as part of the url when viewing the program on the platform.", "required": true, "example": "johns-affiliate-program", "schema": { "type": "string" } }, { "name": "affiliate_id", "in": "path", "description": "The `id` of the affiliate to approve.", "required": true, "example": "janejameson", "schema": { "type": "string" } } ], "x-mint": { "metadata": { "playground": "simple" } } }, "delete": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" }, "email": { "type": "string" }, "company": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } }, "address": { "type": "object", "properties": { "address": { "type": "string" }, "address_two": { "nullable": true }, "postal_code": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } } } }, "meta_data": { "type": "object", "properties": { "foo": { "type": "string" }, "meta": { "type": "string" } } }, "parent_id": { "type": "string" }, "referral_link": { "type": "object", "properties": { "link": { "type": "string" }, "asset_id": { "type": "string" }, "source_id": { "type": "string" } } }, "coupon": { "type": "string" }, "approved": { "type": "boolean" }, "affiliate_group_id": { "nullable": true }, "created_at": { "type": "string" }, "applied_at": { "type": "string" }, "promoted_at": { "nullable": true }, "promotion_method": { "nullable": true }, "custom_fields": { "type": "object", "properties": { "field1": { "type": "string" } } } } }, "example": { "id": "janejameson", "firstname": "Jane", "lastname": "Jameson", "email": "jane@example-blog.inc", "company": { "name": "Example blog Inc.", "description": "Best blog ever" }, "address": { "address": "Rapenburgerstraat 173", "address_two": null, "postal_code": "1011 VM", "city": "Amsterdam", "state": "Noord-Holland", "country": { "code": "NL", "name": "Netherlands" } }, "meta_data": { "foo": "bar", "meta": "data" }, "parent_id": "sandrasanderson", "referral_link": { "link": "https://tapper.inc/johns-cool-product/?ref=nwjinmy", "asset_id": "1-aaaaaa", "source_id": "1-ssssss" }, "coupon": "JANE10OFF", "approved": false, "affiliate_group_id": null, "created_at": "2021-05-27T11:39:03+00:00", "applied_at": "2021-05-27T11:39:03+00:00", "promoted_at": null, "promotion_method": null, "custom_fields": { "field1": "value1" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Disapprove an affiliate", "operationId": "disapproveAnAffiliate", "tags": [ "Programs" ], "parameters": [ { "name": "program_id", "in": "path", "description": "The `id` of the program to add the affiliate too. This id can be found as part of the url when viewing the program on the platform.", "required": true, "example": "johns-affiliate-program", "schema": { "type": "string" } }, { "name": "affiliate_id", "in": "path", "description": "The `id` of the affiliate to approve.", "required": true, "example": "janejameson", "schema": { "type": "string" } } ], "x-mint": { "metadata": { "playground": "simple" } } } }, "/programs/{program_id}/commission-types/": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": {} }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "List program commission types", "operationId": "listProgramCommissionTypes", "tags": [ "Programs" ], "parameters": [ { "name": "program_id", "in": "path", "description": "The `id` of the Program. This id can be found as part of the url when viewing the program on the platform.", "required": true, "example": "johns-affiliate-program", "schema": { "type": "string" } } ] } }, "/programs/{program_id}/levels/": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": {} }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "List program MLM levels", "operationId": "listProgramMlmLevels", "tags": [ "Programs" ], "parameters": [ { "name": "program_id", "in": "path", "description": "The `id` of the Program. This id can be found as part of the url when viewing the program on the platform.", "required": true, "example": "johns-affiliate-program", "schema": { "type": "string" } } ] } }, "/programs/{program_id}/bonuses/": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": {} }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "List program bonuses", "operationId": "listProgramBonuses", "tags": [ "Programs" ], "parameters": [ { "name": "program_id", "in": "path", "description": "The `id` of the Program. This id can be found as part of the url when viewing the program on the platform.", "required": true, "example": "johns-affiliate-program", "schema": { "type": "string" } } ] } }, "/balances/": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "affiliate_id": { "type": "string" }, "balances": { "type": "object", "properties": { "USD": { "type": "number" }, "EUR": { "type": "number" } } } }, "required": [ "affiliate_id", "balances" ] } }, "example": [ { "affiliate_id": "janejameson", "balances": { "USD": 5, "EUR": 35 } }, { "affiliate_id": "deactivatedprogrampublisher", "balances": { "EUR": 30 } }, { "affiliate_id": "peterpeterson", "balances": { "USD": -50 } } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "summary": "List all balances", "operationId": "listAllBalances", "description": "Returns a **non-paginated** list of all non-zero affiliate balances.", "tags": [ "Payments" ] } }, "/payments/{id}/": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string" }, "affiliate": { "type": "object", "properties": { "id": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" } } }, "amount": { "type": "number" }, "currency": { "type": "string" } } }, "example": { "id": "pa_eXampl3", "created_at": "2021-03-29T08:36:07+00:00", "affiliate": { "id": "janejameson", "firstname": "Jane", "lastname": "Jameson" }, "amount": 50, "currency": "USD" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Retrieve payment", "operationId": "retrievePayment", "tags": [ "Payments" ], "parameters": [ { "name": "id", "in": "path", "description": "The `id` of the payment.", "required": true, "example": "pa_eXampl3", "schema": { "type": "string" } } ] }, "delete": { "responses": { "204": { "description": "No Content", "headers": {}, "content": {} }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Cancel payment", "operationId": "cancelPayment", "description": "Cancels the payment and re-adds the amount to the affiliate's balance", "tags": [ "Payments" ], "parameters": [ { "name": "id", "in": "path", "description": "The `id` of the payment.", "required": true, "example": "pa_eXampl3", "schema": { "type": "string" } } ], "x-mint": { "metadata": { "playground": "simple" } } } }, "/payments/": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string" }, "affiliate": { "type": "object", "properties": { "id": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" } } }, "amount": { "type": "number" }, "currency": { "type": "string" } }, "required": [ "id", "created_at", "affiliate", "amount", "currency" ] } }, "example": [ { "id": "pa_eXampl32", "created_at": "2021-03-29T08:36:07+00:00", "affiliate": { "id": "peterpeterson", "firstname": "Peter", "lastname": "Peterson" }, "amount": 50, "currency": "USD" }, { "id": "pa_eXampl3", "created_at": "2021-03-29T08:36:07+00:00", "affiliate": { "id": "janejameson", "firstname": "Jane", "lastname": "Jameson" }, "amount": 50, "currency": "USD" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "summary": "List all payments", "operationId": "listAllPayments", "tags": [ "Payments" ] }, "post": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string" }, "affiliate": { "type": "object", "properties": { "id": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" } } }, "amount": { "type": "number" }, "currency": { "type": "string" } } } }, "example": [ { "id": "pa_eXampl3", "created_at": "2021-03-29T08:36:07+00:00", "affiliate": { "id": "janejameson", "firstname": "Jane", "lastname": "Jameson" }, "amount": 50, "currency": "USD" } ] } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "summary": "Create a payment", "operationId": "createAPayment", "description": "Create a single payment or multiple (using an array of payments)", "tags": [ "Payments" ], "requestBody": { "content": { "application/json": { "example": { "affiliate_id": "janejameson", "amount": 50, "currency": "USD" }, "schema": { "type": "object", "required": [ "affiliate_id", "amount", "currency" ], "properties": { "affiliate_id": { "type": "string", "example": "janejameson", "description": "The affiliate id" }, "amount": { "type": "number", "example": 30.55, "description": "The payment amount" }, "currency": { "type": "string", "example": "USD", "description": "The payment currency" } } } } } }, "x-mint": { "metadata": { "playground": "simple" } } } }, "/clicks/": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClicksCollectionModel" }, "example": [ { "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "created_at": "2023-12-14T00:00:00+00:00", "meta_data": [ { "key": "subid1", "value": "baz" } ], "details": { "os": "Mac OS X", "os_version": "10.15.1", "browser": "Chrome", "browser_version": "81", "referrer": "https://example-blog.inc/check-out-johns-product/", "platform": "Desktop", "landing_page_url": "https://tapper.inc/johns-cool-product/" }, "geolocation": { "country": "United States", "country_code": "US" } } ] } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "summary": "List all clicks", "operationId": "listAllClicks", "tags": [ "Clicks" ], "parameters": [ { "name": "program_id", "in": "query", "description": "The program Id", "example": "johns-affiliate-program", "schema": { "type": "string" } }, { "name": "affiliate_id", "in": "query", "description": "The affiliate Id", "example": "janejameson", "schema": { "type": "string" } }, { "name": "date_from", "in": "query", "description": "Date From, a day in UTC", "example": "2022-01-01", "schema": { "type": "string" } }, { "name": "date_to", "in": "query", "description": "Date To, a day in UTC", "example": "2099-12-31", "schema": { "type": "string" } }, { "name": "meta_data (optional, array) ... Meta Data value filter, example meta_data[key]", "in": "query", "description": "", "required": true, "schema": { "type": "string", "default": "subid1&meta_data[value]=baz" } } ] }, "post": { "responses": { "200": { "description": "OK", "headers": {}, "content": {} }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "summary": "Create a click", "operationId": "createAClick", "description": "In case you elect to use a REST-only implementation, you can use the \"Create a Click\" endpoint to obtain a click id. This click id can be used to create a conversion, by passing it as the `click_id`. You can learn how to set up a full REST-only integration in our [REST integration guide](https://support.tapfiliate.com/en/articles/12682358-how-to-integrate-with-tapfiliate-via-the-rest-api)", "tags": [ "Clicks" ], "requestBody": { "content": { "application/json": { "example": { "referral_code": "janejameson", "source_id": "1-aaaaaa", "meta_data": { "foo": "bar" }, "referrer": "https://their-site.com", "landing_page": "https://my-site.com", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/81.0.4044.129 Safari/537.36" }, "schema": { "type": "object", "properties": {} } } } }, "x-mint": { "metadata": { "playground": "simple" } } } }, "/clicks/{id}/": { "get": { "responses": { "200": { "description": "OK", "headers": {}, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string" }, "meta_data": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "string" } } } }, "details": { "type": "object", "properties": { "os": { "type": "string" }, "os_version": { "type": "string" }, "browser": { "type": "string" }, "browser_version": { "type": "string" }, "referrer": { "type": "string" }, "platform": { "type": "string" }, "landing_page_url": { "type": "string" } } }, "geolocation": { "type": "object", "properties": { "country": { "type": "string" }, "country_code": { "type": "string" } } }, "affiliate": { "type": "object", "properties": { "id": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" } } }, "program": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "currency": { "type": "string" } } }, "link": { "type": "object", "properties": { "asset_id": { "type": "string" }, "source_id": { "type": "string" } } } } }, "example": { "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "created_at": "2023-12-14T00:00:00+00:00", "meta_data": [ { "key": "subid1", "value": "baz" } ], "details": { "os": "Mac OS X", "os_version": "10.15.1", "browser": "Chrome", "browser_version": "81", "referrer": "https://example-blog.inc/check-out-johns-product/", "platform": "Desktop", "landing_page_url": "https://tapper.inc/johns-cool-product/" }, "geolocation": { "country": "United States", "country_code": "US" }, "affiliate": { "id": "janejameson", "firstname": "Jane", "lastname": "Jameson" }, "program": { "id": "johns-affiliate-program", "title": "John's affiliate program", "currency": "USD" }, "link": { "asset_id": "1-aaaaaa", "source_id": "1-ssssss" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "summary": "Get detailed information about click", "operationId": "getDetailedInformationAboutClick", "tags": [ "Clicks" ], "parameters": [ { "name": "id", "in": "path", "description": "The `id` of the click.", "required": true, "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "schema": { "type": "string" } } ] } } }, "components": { "schemas": { "Customer": { "$ref": "#/components/schemas/CustomerFull" }, "CustomerModel": { "type": "object", "properties": { "id": { "type": "string" }, "customer_id": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string" }, "click": { "type": "object", "properties": { "created_at": { "type": "string" }, "referrer": { "type": "string" }, "landing_page": { "type": "string" } } }, "program": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "currency": { "type": "string" } } }, "affiliate": { "type": "object", "properties": { "id": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" } } }, "affiliate_meta_data": { "type": "object", "properties": { "subid1": { "type": "string" } } }, "meta_data": { "type": "object", "properties": { "foo": { "type": "string" } } }, "warnings": { "nullable": true } } }, "CustomersCollectionModel": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "customer_id": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string" }, "click": { "type": "object", "properties": { "created_at": { "type": "string" }, "referrer": { "type": "string" }, "landing_page": { "type": "string" } } }, "program": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "currency": { "type": "string" } } }, "affiliate": { "type": "object", "properties": { "id": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" } } }, "affiliate_meta_data": { "type": "object", "properties": { "subid1": { "type": "string" } } }, "meta_data": { "type": "object", "properties": { "foo": { "type": "string" } } }, "warnings": { "nullable": true } } } }, "Conversion": { "$ref": "#/components/schemas/ConversionFull" }, "ConversionModel": { "type": "object", "properties": { "id": { "type": "number" }, "external_id": { "type": "string" }, "amount": { "type": "number" }, "click": { "type": "object", "properties": { "created_at": { "type": "string" }, "referrer": { "type": "string" }, "landing_page": { "type": "string" } } }, "commissions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "conversion_sub_amount": { "type": "number" }, "amount": { "type": "number" }, "commission_type": { "type": "string" }, "approved": { "type": "boolean" }, "affiliate": { "type": "object", "properties": { "id": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" } } }, "kind": { "type": "string" }, "currency": { "type": "string" }, "created_at": { "nullable": true }, "payout": { "nullable": true }, "comment": { "nullable": true }, "final": { "nullable": true }, "commission_name": { "type": "string" } } } }, "program": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "currency": { "type": "string" } } }, "affiliate": { "type": "object", "properties": { "id": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" } } }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "customer_id": { "type": "string" }, "status": { "type": "string" } } }, "affiliate_meta_data": { "type": "object", "properties": { "subid1": { "type": "string" } } }, "meta_data": { "type": "object", "properties": { "foo": { "type": "string" }, "tap": { "type": "string" } } }, "created_at": { "type": "string" }, "warnings": { "nullable": true }, "tracking_source": { "nullable": true } } }, "ConversionsCollectionModel": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "external_id": { "type": "string" }, "amount": { "type": "number" }, "click": { "type": "object", "properties": { "created_at": { "type": "string" }, "referrer": { "type": "string" }, "landing_page": { "type": "string" } } }, "commissions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "conversion_sub_amount": { "type": "number" }, "amount": { "type": "number" }, "commission_type": { "type": "string" }, "approved": { "type": "boolean" }, "affiliate": { "type": "object", "properties": { "id": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" } } }, "kind": { "type": "string" }, "currency": { "type": "string" }, "created_at": { "nullable": true }, "payout": { "nullable": true }, "comment": { "nullable": true }, "final": { "nullable": true }, "commission_name": { "type": "string" } } } }, "program": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "currency": { "type": "string" } } }, "affiliate": { "type": "object", "properties": { "id": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" } } }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "customer_id": { "type": "string" }, "status": { "type": "string" } } }, "meta_data": { "type": "object", "properties": { "foo": { "type": "string" }, "tap": { "type": "string" } } }, "created_at": { "type": "string" }, "warnings": { "nullable": true }, "affiliate_meta_data": { "type": "object", "properties": { "subid1": { "type": "string" } } }, "tracking_source": { "nullable": true } } } }, "Commission": { "$ref": "#/components/schemas/CommissionFull" }, "CommissionModel": { "type": "object", "properties": { "id": { "type": "number" }, "conversion_sub_amount": { "type": "number" }, "amount": { "type": "number" }, "commission_type": { "type": "string" }, "approved": { "type": "boolean" }, "affiliate": { "type": "object", "properties": { "id": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" } } }, "conversion": { "type": "object", "properties": { "id": { "type": "number" } } }, "kind": { "type": "string" }, "currency": { "type": "string" }, "created_at": { "nullable": true }, "payout": { "nullable": true }, "comment": { "nullable": true }, "final": { "nullable": true }, "finalization_date": { "nullable": true }, "commission_name": { "type": "string" } } }, "CommissionsCollectionModel": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "amount": { "type": "number" }, "approved": { "type": "boolean" }, "created_at": { "type": "string" }, "commission_type": { "type": "string" }, "comment": { "nullable": true }, "conversion": { "type": "object", "properties": { "id": { "type": "number" } } }, "payout": { "nullable": true }, "affiliate": { "type": "object", "properties": { "id": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" } } }, "kind": { "type": "string" }, "currency": { "type": "string" }, "final": { "nullable": true }, "finalization_date": { "nullable": true }, "commission_name": { "type": "string" }, "conversion_sub_amount": { "type": "number" } }, "required": [ "id", "amount", "approved", "created_at", "commission_type", "comment", "conversion", "payout", "affiliate", "kind", "currency", "final", "finalization_date", "commission_name", "conversion_sub_amount" ] } }, "Affiliate": { "$ref": "#/components/schemas/AffiliateFull" }, "AffiliateModel": { "type": "object", "properties": { "id": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" }, "email": { "type": "string" }, "company": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } }, "address": { "type": "object", "properties": { "address": { "type": "string" }, "address_two": { "nullable": true }, "postal_code": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } } } }, "meta_data": { "type": "object", "properties": { "foo": { "type": "string" }, "meta": { "type": "string" } } }, "parent_id": { "type": "string" }, "affiliate_group_id": { "nullable": true }, "created_at": { "type": "string" }, "promoted_at": { "nullable": true }, "promotion_method": { "nullable": true }, "custom_fields": { "type": "object", "properties": { "field1": { "type": "string" } } } } }, "AffiliateProspect": { "$ref": "#/components/schemas/AffiliateProspectFull" }, "AffiliateProspectModel": { "type": "object", "properties": { "id": { "type": "string" }, "firstname": { "type": "string" }, "lastname": { "type": "string" }, "email": { "type": "string" }, "company": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } }, "address": { "type": "object", "properties": { "address": { "type": "string" }, "address_two": { "nullable": true }, "postal_code": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } } } }, "signup_source": { "type": "string" }, "referral_link": { "type": "object", "properties": { "link": { "type": "string" }, "asset_id": { "type": "string" }, "source_id": { "type": "string" } } }, "created_at": { "type": "string" }, "promoted_at": { "nullable": true }, "promotion_method": { "nullable": true } } }, "Program": { "$ref": "#/components/schemas/ProgramFull" }, "ClicksCollectionModel": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string" }, "meta_data": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "string" } } } }, "details": { "type": "object", "properties": { "os": { "type": "string" }, "os_version": { "type": "string" }, "browser": { "type": "string" }, "browser_version": { "type": "string" }, "referrer": { "type": "string" }, "platform": { "type": "string" }, "landing_page_url": { "type": "string" } } }, "geolocation": { "type": "object", "properties": { "country": { "type": "string" }, "country_code": { "type": "string" } } } } } }, "ConversionFull": { "type": "object", "properties": { "id": { "type": "number", "example": 1, "description": "The conversion's numeric id" }, "external_id": { "type": "string", "example": "foobar1", "description": "A a unique id for this conversion. It can be anything that is meaningful to you, like an order number, user id, email adres etc.. After a conversion has taken place, you can find this id alongside the conversion on our platform. This makes it very easy to cross-reference data on our platform with your own administration. This id has to be unique for every conversion." }, "amount": { "type": "number", "example": 30.55, "description": "The conversion amount" }, "click": { "$ref": "#/components/schemas/ClickSmall", "description": "A click object" }, "commissions": { "type": "array", "items": {}, "description": "An array of commission objects" }, "program": { "$ref": "#/components/schemas/ProgramSmall", "description": "Details of the program in which this conversion was created" }, "affiliate": { "$ref": "#/components/schemas/AffiliateSmall", "description": "Details about the affiliate that created tgus conversion" }, "tracking_source": { "type": "string", "example": "cookie-js", "description": "How the conversion was tracked: `coupon-js`, `cookie-js`, `recurring-js`, `coupon-api`, `cookie-api`, `click-id-api`, `asset-source-api`, `referral-code-api`, `recurring-api` or `recurring-auto`. `null` if it is not known. Returned when retrieving or listing conversions.", "nullable": true } } }, "CustomerFull": { "type": "object", "properties": { "id": { "type": "string", "example": "cu_eXampl3", "description": "The Tapfiliate generated `id` of the customer." }, "customer_id": { "type": "string", "example": "USER123", "description": "The id for this customer in your system. The customer id should be unique for each customer." }, "status": { "type": "string", "example": "trial", "description": "The current status of the customer. You can read more about statuses, and their implications [in this article](https://support.tapfiliate.com/en/articles/3092024-what-are-customers#customer-status)" }, "click": { "$ref": "#/components/schemas/ClickSmall", "description": "A click object" }, "program": { "$ref": "#/components/schemas/ProgramSmall", "description": "Details of the program in which this conversion was created" }, "affiliate": { "$ref": "#/components/schemas/AffiliateSmall", "description": "Details about the affiliate that created tgus conversion" } } }, "AffiliateFull": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "example": "janejameson", "description": "The affiliate's id." }, "address": { "$ref": "#/components/schemas/Address", "description": "The company's address data" } } }, "AffiliateName": { "type": "object", "required": [ "firstname", "lastname" ], "properties": { "firstname": { "type": "string", "example": "Jane", "description": "The affiliate's firstname" }, "lastname": { "type": "string", "example": "Jameson", "description": "The affiliate's lastname" } } }, "AffiliateSmall": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "example": "janejameson", "description": "The affiliate's id" } } }, "AffiliatePayout": { "type": "object", "properties": { "payout_methods": { "type": "object", "properties": { "id": { "type": "string", "example": "paypal", "description": "The payout method's id" }, "title": { "type": "string", "example": "Paypal", "description": "The payout method's title" }, "details": { "type": "object", "properties": {}, "description": "The fields and their values" }, "primary": { "type": "boolean", "example": true, "description": "Wether the affiliate has selected this payout method as their primary payout method" } } } } }, "AddAffiliateToProgram": { "type": "object", "required": [ "affiliate" ], "properties": { "affiliate": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "example": "billmurray", "description": "The `id` of the affiliate" } } }, "approved": { "type": "boolean", "example": true, "description": "An optional approval status. Valid values are: `true` (Approved, default) | `false` (Disapproved) | `null` (Pending)", "nullable": true }, "coupon": { "type": "string", "example": "JANE10OFF", "description": "An optional coupon for this affiliate" } } }, "AffiliateCreate": { "type": "object", "properties": { "email": { "type": "string", "example": "jane@example", "description": "blog.inc (string, required) - The affiliate's email" }, "password": { "type": "string", "example": "password1234", "description": "The password for the new account. If no password is given, one is generated and passed in the response" }, "company": { "$ref": "#/components/schemas/Company", "description": "The affiliate's company data" }, "address": { "$ref": "#/components/schemas/Address", "description": "The affiliate's address" }, "custom_fields": { "type": "object", "properties": {}, "description": "Custom fields" } } }, "AffiliateProspectName": { "type": "object", "required": [ "firstname", "lastname" ], "properties": { "firstname": { "type": "string", "example": "Peter", "description": "The affiliate prospect's firstname" }, "lastname": { "type": "string", "example": "Prospect", "description": "The affiliate prospect's lastname" } } }, "AffiliateProspectFull": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "example": "peterpeterson", "description": "The affiliate prospect's id" }, "address": { "$ref": "#/components/schemas/Address", "description": "The company's address data" } } }, "AffiliateProspectCreate": { "type": "object", "properties": { "email": { "type": "string", "example": "jane@example", "description": "blog.inc (string, required) - The affiliate's email" }, "company": { "$ref": "#/components/schemas/Company", "description": "The affiliate prospect's company data" }, "address": { "$ref": "#/components/schemas/Address", "description": "The affiliate prospect's address" }, "program_id": { "type": "string", "example": "johns", "description": "affiliate-program (string, optional) - The program to add the affiliate prospect to. If none is passed, the affiliate prospect will be added to the default program" }, "affiliate_group_id": { "type": "string", "example": "ag_1234", "description": "The affiliate group to add the affiliate prospect to" } } }, "Note": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Great person!", "description": "The Note's content" } } }, "Company": { "type": "object", "properties": { "name": { "type": "string", "example": "Tapfiliate", "description": "The company's name" } } }, "MetaData": { "type": "object", "properties": { "meta_data": { "type": "object", "properties": {}, "description": "Meta data for this resource" } } }, "Address": { "type": "object", "required": [ "address", "postal_code", "city", "country" ], "properties": { "address": { "type": "string", "example": "Rapenburgerstraat 173", "description": "The company's address" }, "postal_code": { "type": "string", "example": "1011VM", "description": "The company's postal code" }, "city": { "type": "string", "example": "Amsterdam", "description": "The company's city" }, "state": { "type": "string", "example": "Noord", "description": "Holland (string, optional) - The company's state" }, "country": { "$ref": "#/components/schemas/Country", "description": "The company's contry data" } } }, "PayoutFull": { "type": "object", "properties": { "id": { "type": "number", "example": 123, "description": "The numeric id of the payout" }, "amount": { "type": "number", "example": 88.55, "description": "The payout amount" }, "affiliate": { "$ref": "#/components/schemas/AffiliatePayout" }, "paid": { "type": "boolean", "example": true, "description": "Wether this payout was markes as paid" } } }, "Country": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "example": "NL", "description": "The country's ISO_3166-1 code (https://en.wikipedia.org/wiki/ISO_3166-1)" } } }, "ProgramFull": { "type": "object", "properties": { "cookie_time": { "type": "number", "example": 45, "description": "The cookie time in days for this program" }, "status": { "type": "string", "enum": [ "active", "archived" ], "description": "The program's status: `active`, or `archived` once the advertiser has archived it" } } }, "ProgramSmall": { "type": "object", "properties": { "id": { "type": "string", "example": "johns", "description": "affiliate-program (string) - The programs's id" }, "title": { "type": "string", "example": "John's affiliate program", "description": "The programs's title" }, "currency": { "type": "string", "example": "USD", "description": "The program's currency" } } }, "CommissionFull": { "type": "object", "properties": { "id": { "type": "number", "example": 123, "description": "The numeric id of the commission" }, "amount": { "type": "number", "example": 55, "description": "The commission amount" }, "approved": { "type": "boolean", "example": true, "description": "The approval status of this commission ( null | true | false )", "nullable": true }, "kind": { "type": "string", "example": "regular", "description": "The kind of commission ( regular | recurring | level )" }, "payout": { "type": "number", "example": 321, "description": "The payout id for this commission (only set if this commission was payed out)" }, "commission_type": { "type": "string", "example": "standard", "description": "The identifier of the Commission Type for this commission." }, "conversion_sub_amount": { "type": "number", "example": 550, "description": "The conversion amount on which the commission amount is based" }, "comment": { "type": "string", "example": "Foo", "description": "An optional comment for the affiliate" } } }, "ClickSmall": { "type": "object", "properties": { "referrer": { "type": "string", "example": "\"https://example", "description": "blog.inc/check-out-johns-product/\" (string) - The HTTP referrer. Will be used in reporting" }, "landing_page": { "type": "string", "example": "\"https://tapper.inc/johns", "description": "cool-product/\" (string) - The current page. Will be used in reporting" } } }, "ClickCreate": { "type": "object", "required": [ "referral_code" ], "properties": { "referral_code": { "type": "string", "example": "janejameson", "description": "The affiliate's referral code. Obtained from the url" }, "source_id": { "type": "string", "example": "1", "description": "aaaaaa (string, optional) - The source id used by the affiliate (if any). Obtained from the url" }, "meta_data": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "example": "value", "description": "A key value pair. Multiple allowedtype" } }, "description": "Any meta data parameters passed by the affiliate." }, "referrer": { "type": "string", "example": "https://averycoolblog.com", "description": "The HTTP referrer. Will be used in reporting" }, "landing_page": { "type": "string", "example": "https://tapfiliate.com/signup", "description": "The current page. Will be used in reporting" }, "user_agent": { "type": "string", "example": "Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0", "description": "The full user agent string for the client. Will be used in reporting" }, "ip": { "type": "string", "example": "8.8.8.8", "description": "The user IP address. Will be used in reporting" } } }, "CreatedAt": { "type": "object", "properties": { "created_at": { "type": "string", "example": "2021-03-31T08:21:02+0000", "description": "The creation timestamp" } } }, "ErrorList": { "type": "object", "description": "Business and validation errors raised by an endpoint.", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "description": "Machine-readable code, on 409 responses." }, "property_path": { "type": "string", "description": "The invalid field, on validation errors." } }, "required": [ "message" ] } } }, "required": [ "errors" ] }, "RequestError": { "type": "object", "description": "Errors raised before the endpoint runs: authentication, access, unknown path, server error.", "properties": { "message": { "type": "string" }, "code": { "type": "integer" }, "traceId": { "type": "string", "description": "Send this to support to find the request." } }, "required": [ "message", "code" ] } }, "responses": { "BadRequest": { "description": "The request is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorList" }, "example": { "errors": [ { "message": "Missing mandatory parameter(s)" } ] } } } }, "Unauthorized": { "description": "The API key is missing or wrong", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" }, "example": { "message": "Authentication Failed.", "code": 401 } } } }, "Forbidden": { "description": "No API access or no permission for this action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" }, "example": { "message": "Forbidden", "code": 403, "traceId": "04ed655728a22bc0d39f" } } } }, "NotFound": { "description": "The object does not exist or belongs to another account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestError" }, "example": { "message": "Not Found", "code": 404, "traceId": "7ae8e92b77572da03805" } } } } }, "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "Your API key, from your Tapfiliate account settings." } } }, "tags": [ { "name": "Customers", "description": "People who signed up or paid after being referred by an affiliate. With recurring or lifetime commissions, later conversions for the same customer go to the same affiliate." }, { "name": "Conversions", "description": "Sales and other actions you pay commissions for. Each conversion has one or more commissions." }, { "name": "Commissions", "description": "What an affiliate earns for a conversion. Approve or disapprove them before payout." }, { "name": "Affiliates", "description": "The partners who promote your programs, with their meta data, notes, payout methods and balances." }, { "name": "Affiliate Groups", "description": "Groups for organising your affiliates." }, { "name": "Affiliate Prospects", "description": "People who signed up through a recruitment source but are not affiliates yet." }, { "name": "Programs", "description": "Your affiliate programs, the affiliates in them and their commission settings." }, { "name": "Payments", "description": "Settle affiliate balances and look up past payments." }, { "name": "Clicks", "description": "Visits through affiliate links, the first step of attribution." } ], "security": [ { "ApiKey": [] } ] }