Create a Promotion

POST /api/promotions deprecated

Requires: Promotions.Promotions, Promotions.Promotions.Create, merchant scope.

Create a new Promotion

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 CreatePromotionDto. See the Request body section below for its fields.

cURL PowerShell TypeScript C# Python

cURL

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

PowerShell

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

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

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

npm install @winkpg/winkpg-api

TypeScript (SDK)

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

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

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

TypeScript (raw HTTP)

const response = await fetch('{{BASE_URL}}/api/promotions', {
  method: 'POST',
  headers: {
    "api-key": "{{API_KEY}}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "code": "",
    "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 PromotionsApi(config);
var body = JsonSerializer.Deserialize<CreatePromotionDto>("""
    {
      "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "code": "",
      "name": ""
    }
    """);

var result = await api.PromotionsCreateAsync(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/promotions");
request.Headers.Add("api-key", "{{API_KEY}}");

request.Content = new StringContent("""
    {
      "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "code": "",
      "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.PromotionsApi(client)
    body = winkpg_api.CreatePromotionDto.from_dict({
      "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "code": "",
      "name": ""
    })
    result = api.promotions_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",
  "code": "",
  "name": ""
}

response = requests.request(
    "POST",
    "{{BASE_URL}}/api/promotions",
    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 promotion. Required on create, and immutable afterwards: an update that names a different merchant is refused rather than silently moving the promotion and the ledger entries that point at it. nullable
`code` required	string	The code a payer types. Stored trimmed and upper-cased, and unique among the merchant's promotions, so `save10` and `SAVE10` are the same code rather than two. Conditional: When Code is not empty. nullablemax length 64
`name` required	string	Operator-facing promotion name. Never shown to payers. nullablemax length 128
`description` required	string	Free-text description of the promotion. nullablemax length 1024
`discountType` required	all of PromotionDiscountType	Whether the value is a percentage or a flat amount.
`value` required	number (double)	The percentage, or the flat amount in `currency`. Conditional: When DiscountType == Percent. Must be <= 100. Conditional: When DiscountType == Flat. Must be <= 1000000. min 0
`currency` required	string	The ISO 4217 currency. Required for a flat amount, and optional for a percentage, where it narrows the promotion to one currency rather than denominating anything. Required: When DiscountType == Flat. Conditional: When Currency is not empty. Length: 3 to 3. nullable
`startsAtUtc` required	string (date-time)	UTC moment the promotion starts being accepted. `null` starts it immediately. nullable
`endsAtUtc` required	string (date-time)	UTC moment the promotion stops being accepted. `null` leaves it open. nullable
`maxRedemptions` required	integer (int32)	How many times the promotion may be redeemed in total. `null` for no ceiling. Conditional: When MaxRedemptions is not null. Must be > 0. nullable
`maxRedemptionsPerCustomer` required	integer (int32)	How many times one customer may redeem it. `null` for no ceiling. A promotion that carries one refuses a redemption that identifies no customer. Conditional: When MaxRedemptionsPerCustomer is not null. Must be > 0. nullable
`minimumSubtotal` required	number (double)	The smallest amount the promotion applies to. `null` for no floor. Conditional: When MinimumSubtotal is not null. Must be >= 0. nullable
`appliesToScope` required	all of PromotionAppliesToScope	What the promotion may be applied to.
`appliesToTargetIds` required	array of string (uuid)	The pages, products or plans the scope names. Required by every scope except `Any`, which ignores it. Conditional: When AppliesToScope != Any. Conditional: When AppliesToTargetIds is not null. nullable
`durationMode` required	all of PromotionDurationMode	How long the discount runs on a recurring charge.
`durationCycles` required	integer (int32)	How many billing cycles the discount runs for. Required by `Cycles`, and ignored by every other mode. Required: When DurationMode == Cycles. nullable
`isActive` required	boolean	Whether the promotion is accepted. A deactivated promotion keeps its ledger.

This request body has no documented fields.