# PUT /api/campaigns/{id} Update a Campaign Update an existing Campaign by id **Operation ID:** `campaignsUpdate` ## Authorization Requires: Campaigns.Campaigns, Campaigns.Campaigns.Update, merchant scope. Required permissions: - `Campaigns.Campaigns` - `Campaigns.Campaigns.Update` ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | id | path | yes | string(uuid) | | | suppressNulls | query | no | boolean | If true, omit properties with null values. | ## Request Body **Content type:** `application/json` Schema: `UpdateCampaignDto` Properties: - `merchantId` (string(uuid)) required: 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. - `name` (string) required: Operator-facing campaign name. Never shown to payers. - `description` (string): Free-text description of the campaign. - `startsAtUtc` (string(date-time)): UTC moment the campaign starts accepting payments. `null` means it starts as soon as it is activated. - `endsAtUtc` (string(date-time)): UTC moment the campaign stops accepting payments. `null` means it stays open until it is ended explicitly. - `inactiveMessage` (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. - `externalReference` (string): The merchant's own identifier for this campaign, carried through to reporting. - `maxCompletions` (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. - `maxTotalAmount` (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. - `goalAmount` (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. - `refundsReduceTotal` (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` (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` (object): 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. - `concurrencyStamp` (string) **Content type:** `text/json` Schema: `UpdateCampaignDto` Properties: - `merchantId` (string(uuid)) required: 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. - `name` (string) required: Operator-facing campaign name. Never shown to payers. - `description` (string): Free-text description of the campaign. - `startsAtUtc` (string(date-time)): UTC moment the campaign starts accepting payments. `null` means it starts as soon as it is activated. - `endsAtUtc` (string(date-time)): UTC moment the campaign stops accepting payments. `null` means it stays open until it is ended explicitly. - `inactiveMessage` (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. - `externalReference` (string): The merchant's own identifier for this campaign, carried through to reporting. - `maxCompletions` (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. - `maxTotalAmount` (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. - `goalAmount` (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. - `refundsReduceTotal` (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` (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` (object): 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. - `concurrencyStamp` (string) **Content type:** `application/*+json` Schema: `UpdateCampaignDto` Properties: - `merchantId` (string(uuid)) required: 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. - `name` (string) required: Operator-facing campaign name. Never shown to payers. - `description` (string): Free-text description of the campaign. - `startsAtUtc` (string(date-time)): UTC moment the campaign starts accepting payments. `null` means it starts as soon as it is activated. - `endsAtUtc` (string(date-time)): UTC moment the campaign stops accepting payments. `null` means it stays open until it is ended explicitly. - `inactiveMessage` (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. - `externalReference` (string): The merchant's own identifier for this campaign, carried through to reporting. - `maxCompletions` (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. - `maxTotalAmount` (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. - `goalAmount` (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. - `refundsReduceTotal` (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` (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` (object): 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. - `concurrencyStamp` (string) ## Responses ### 200 OK **Content type:** `application/json` Schema: `CampaignDto` Properties: - `extraProperties` (object) - `id` (string(uuid)) - `creationTime` (string(date-time)): The date and time when this entity was created. - `creatorId` (string(uuid)): The ID of the user who created this entity. - `lastModificationTime` (string(date-time)): The date and time when this entity was last modified. - `lastModifierId` (string(uuid)): The ID of the user who last modified this entity. - `isDeleted` (boolean): Indicates whether this entity has been deleted. - `deleterId` (string(uuid)): The ID of the user who deleted this entity, if it is deleted. - `deletionTime` (string(date-time)): The date and time when this entity was deleted, if it is deleted. - `merchantId` (string(uuid)): The merchant that owns this campaign. - `name` (string): Operator-facing campaign name. - `description` (string): Free-text description of the campaign. - `status` (object): The campaign's status right now. A running campaign whose scheduled end has already passed reads as `Ended` here, without anything having been written to it. - `endedReason` (object): Why the campaign ended, or `null` while it has not ended. A campaign that ended only because its window closed reports `Schedule`. - `endedAtUtc` (string(date-time)): UTC moment the campaign was ended or archived out of a running state, or `null` while it has not been. A campaign that reads as ended only because its window closed carries none: its `endsAtUtc` is its end. - `isAcceptingPayments` (boolean): Whether member payment links may transact through this campaign right now. False before the scheduled start, and for any status other than active. - `startsAtUtc` (string(date-time)): UTC moment the campaign starts accepting payments. - `endsAtUtc` (string(date-time)): UTC moment the campaign stops accepting payments. - `inactiveMessage` (string): Payer-facing message shown while the campaign is not accepting payments. - `externalReference` (string): The merchant's own identifier for this campaign. - `overrides` (object): Branding and text laid over every hosted page and payment link in the campaign when it renders. A member that is `null` inherits each member page's own value. - `clonedFromCampaignId` (string(uuid)): The campaign this one was cloned from, or `null` for a campaign created from scratch. The source may have been deleted since; the reference is kept either way. - `maxCompletions` (integer(int32)): The number of approved payments at which the campaign ends on its own, or `null` for no completion cap. - `maxTotalAmount` (number(double)): The net collected amount at which the campaign ends on its own, or `null` for no amount cap. - `goalAmount` (number(double)): The amount the campaign is aiming to collect, or `null` for no goal. - `refundsReduceTotal` (boolean): Whether refunds, voids and reversals reduce the collected total. - `showProgress` (boolean): Whether the campaign's progress is shown to payers and published anonymously. - `completedCount` (integer(int32)): Approved payments counted so far. Zero on a campaign that has taken none. - `approvedTotal` (number(double)): The approved base amount collected so far, before any refund. - `refundedTotal` (number(double)): The amount refunded, voided or reversed so far. - `netTotal` (number(double)): The total the caps and the goal are measured against: approved less refunded when refunds reduce the total, approved otherwise. - `lastCompletedAtUtc` (string(date-time)): When the most recent approved payment was counted (UTC), or `null` before the first. - `percentOfGoal` (integer(int32)): The net total as a whole percentage of the goal, not capped at 100, or `null` without a goal. - `concurrencyStamp` (string): Optimistic concurrency token. ### 403 Forbidden **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 401 Unauthorized **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 400 Bad Request **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 404 Not Found **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 501 Not Implemented **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 500 Internal Server Error **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### default The request failed. The body carries the standard error envelope: a machine-readable `error.code`, a human-readable `error.message`, and `error.validationErrors` when the failure was a validation rejection. See the error-code reference in this document's description for the values `error.code` can take. **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ### 429 The request was refused because a rate limit was exceeded, or because something a later retry can clear stopped it. A rate limit refusal carries an `application/problem+json` body: wait at least the interval `Retry-After` names before retrying, then back off. Limits are tuned per deployment, so read the allowance from the response headers rather than assuming a fixed ceiling. Any other refusal carries the standard error envelope as `application/json`, and its `error.code` names the cause. **Content type:** `application/problem+json` Schema: `RateLimitProblemDetails` Properties: - `type` (string) required: The problem type identifier. Always the same value: the failure is the status code itself, so there is no sub-type for a caller to branch on. - `title` (string) required: A short, human-readable summary of the problem type. - `status` (integer(int32)) required: The HTTP status code, repeated in the body as the problem-details format defines. - `detail` (string) required: A human-readable explanation of this occurrence of the problem. - `retryAfterSeconds` (integer(int32)) required: How long to wait before retrying, in whole seconds, carrying the same figure as the `Retry-After` header. Always at least one: a value of zero would invite an immediate retry that is certain to be rejected again. **Content type:** `application/json` Schema: `RemoteServiceErrorResponse` Properties: - `error` (RemoteServiceErrorInfo) ## 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 UpdateCampaignDto. See the Request body section below for its fields. ### cURL ```bash curl -X PUT "{{BASE_URL}}/api/campaigns/{id}" \ -H "api-key: {{API_KEY}}" \ -H "Content-Type: application/json" \ -d '{ "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "" }' ``` ### PowerShell ```powershell $headers = @{ 'api-key' = '{{API_KEY}}' } $body = @' { "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "" } '@ $response = Invoke-RestMethod -Method PUT -Uri '{{BASE_URL}}/api/campaigns/{id}' ` -Headers $headers -ContentType 'application/json' -Body $body ``` ### TypeScript (SDK) ```bash npm install @winkpg/winkpg-api ``` ```typescript import { Configuration, CampaignsApi } from '@winkpg/winkpg-api'; const api = new CampaignsApi(new Configuration({ basePath: '{{BASE_URL}}', apiKey: '{{API_KEY}}', })); const { data } = await api.campaignsUpdate("3fa85f64-5717-4562-b3fc-2c963f66afa6", { "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "" }); ``` ### TypeScript (raw HTTP) ```typescript const response = await fetch('{{BASE_URL}}/api/campaigns/{id}', { method: 'PUT', headers: { "api-key": "{{API_KEY}}", "Content-Type": "application/json", }, body: JSON.stringify({ "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "" }), }); const data = await response.json(); ``` ### C# (SDK) ```bash dotnet add package WinkPg.Api.Client ``` ```csharp 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(""" { "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "" } """); var result = await api.CampaignsUpdateAsync(Guid.Parse("3fa85f64-5717-4562-b3fc-2c963f66afa6"), body); ``` ### C# (raw HTTP) ```csharp using System.Text; using var http = new HttpClient { BaseAddress = new Uri("{{BASE_URL}}") }; var request = new HttpRequestMessage(new HttpMethod("PUT"), "/api/campaigns/{id}"); 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(); ``` ### Python (SDK) ```bash pip install winkpg-api ``` ```python 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.UpdateCampaignDto.from_dict({ "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "" }) result = api.campaigns_update("3fa85f64-5717-4562-b3fc-2c963f66afa6", body) ``` ### Python (raw HTTP) ```bash pip install requests ``` ```python import requests headers = { "api-key": "{{API_KEY}}", "Content-Type": "application/json", } body = { "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "" } response = requests.request( "PUT", "{{BASE_URL}}/api/campaigns/{id}", headers=headers, json=body, ) response.raise_for_status() data = response.json() ``` ## See also - [All documentation](https://devportal-simpay-sbx.winkpg.io/llms.txt): the machine-readable index of every public page on this site.