Create a Campaign

POST /api/campaigns deprecated

Requires: Campaigns.Campaigns, Campaigns.Campaigns.Create, merchant scope.

Create a new Campaign

Signed in, you can send this request to your own sandbox merchant from the console and read the answer. Sign in to try it.

Example request

Every block below sends the same request. Replace {{BASE_URL}} with the address of the API you are calling and {{API_KEY}} with your own key.

The request body is a CreateCampaignDto. See the Request body section below for its fields.

cURL PowerShell TypeScript C# Python

cURL

curl -X POST "{{BASE_URL}}/api/campaigns" \
  -H "api-key: {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
  "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": ""
}'

PowerShell

$headers = @{
    'api-key' = '{{API_KEY}}'
}

$body = @'
{
  "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": ""
}
'@

$response = Invoke-RestMethod -Method POST -Uri '{{BASE_URL}}/api/campaigns' `
    -Headers $headers -ContentType 'application/json' -Body $body

npm install @winkpg/winkpg-api

TypeScript (SDK)

import { Configuration, CampaignsApi } from '@winkpg/winkpg-api';

const api = new CampaignsApi(new Configuration({
  basePath: '{{BASE_URL}}',
  apiKey: '{{API_KEY}}',
}));

const { data } = await api.campaignsCreate({
  "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": ""
});

TypeScript (raw HTTP)

const response = await fetch('{{BASE_URL}}/api/campaigns', {
  method: 'POST',
  headers: {
    "api-key": "{{API_KEY}}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": ""
  }),
});

const data = await response.json();

dotnet add package WinkPg.Api.Client

C# (SDK)

using WinkPg.Api.Client.Api;
using WinkPg.Api.Client.Client;
using System.Text.Json;

var config = new Configuration { BasePath = "{{BASE_URL}}" };
config.AddApiKey("api-key", "{{API_KEY}}");

var api = new CampaignsApi(config);
var body = JsonSerializer.Deserialize<CreateCampaignDto>("""
    {
      "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": ""
    }
    """);

var result = await api.CampaignsCreateAsync(body);

C# (raw HTTP)

using System.Text;

using var http = new HttpClient { BaseAddress = new Uri("{{BASE_URL}}") };

var request = new HttpRequestMessage(new HttpMethod("POST"), "/api/campaigns");
request.Headers.Add("api-key", "{{API_KEY}}");

request.Content = new StringContent("""
    {
      "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": ""
    }
    """, Encoding.UTF8, "application/json");

var response = await http.SendAsync(request);
response.EnsureSuccessStatusCode();
var json = await response.Content.ReadAsStringAsync();

pip install winkpg-api

Python (SDK)

import winkpg_api

configuration = winkpg_api.Configuration(host="{{BASE_URL}}")
configuration.api_key["ApiKey"] = "{{API_KEY}}"

with winkpg_api.ApiClient(configuration) as client:
    api = winkpg_api.CampaignsApi(client)
    body = winkpg_api.CreateCampaignDto.from_dict({
      "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": ""
    })
    result = api.campaigns_create(body)

pip install requests

Python (raw HTTP)

import requests

headers = {
    "api-key": "{{API_KEY}}",
    "Content-Type": "application/json",
}

body = {
  "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": ""
}

response = requests.request(
    "POST",
    "{{BASE_URL}}/api/campaigns",
    headers=headers,
    json=body,
)
response.raise_for_status()
data = response.json()

Parameters

Name	In	Type	Description
`suppressNulls` required	query	boolean	If true, omit properties with null values.

Request body

application/json , required

Field	Type	Description
`merchantId` required	string (uuid)	The merchant that owns this campaign. Required on create, and immutable afterwards: an update that names a different merchant is refused rather than silently moving the campaign and every link pointing at it. nullable
`name` required	string	Operator-facing campaign name. Never shown to payers. nullablemax length 128
`description` required	string	Free-text description of the campaign. nullablemax length 1024
`startsAtUtc` required	string (date-time)	UTC moment the campaign starts accepting payments. `null` means it starts as soon as it is activated. nullable
`endsAtUtc` required	string (date-time)	UTC moment the campaign stops accepting payments. `null` means it stays open until it is ended explicitly. nullable
`inactiveMessage` required	string	Payer-facing message shown when someone opens a member link while the campaign is not accepting payments. `null` falls back to the platform default copy. nullablemax length 512
`externalReference` required	string	The merchant's own identifier for this campaign, carried through to reporting. nullablemax length 128
`maxCompletions` required	integer (int32)	The number of approved payments at which the campaign ends on its own, or `null` for no completion cap. Must be greater than zero when set. Enforced exactly: the payment that would exceed it is refused at submit, and two payers cannot both take the last slot. nullablemin 0
`maxTotalAmount` required	number (double)	The net collected amount at which the campaign ends on its own, or `null` for no amount cap. Must be greater than zero when set. A payment already in flight when the cap is reached still completes, so the total can overshoot by the payments in flight at that instant. nullablemin 0
`goalAmount` required	number (double)	The amount the campaign is aiming to collect, or `null` for no goal. Must be greater than zero when set. Drives the progress bar and the `Campaign.Milestone` and `Campaign.GoalReached` notifications; reaching it never ends the campaign. nullablemin 0
`refundsReduceTotal` required	boolean	Whether refunds, voids and reversals reduce the collected total the caps and the goal are measured against. Off by default: the total only ever goes up.
`showProgress` required	boolean	Whether the campaign's count, total and goal are shown to payers on its hosted pages and links, and published at `GET /api/campaigns/{id}/progress`. Off by default: nothing about the campaign leaves the merchant's own surfaces.
`overrides` required	all of CampaignOverridesDto	Branding and text laid over every hosted page and payment link in the campaign when it renders. On an update, leave this out (or send `null`) to keep the overrides the campaign already has; send an object to replace them all, where each member left out or `null` inherits the member page's own value.

This request body has no documented fields.