Get a ContractPlan

GET /api/contract-plans/{id} deprecated

Requires: Customers.ContractPlans, merchant scope.

Requires API key scope: admin (Administration)

Return the full record for a ContractPlan with the given id

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

cURL PowerShell TypeScript C# Python

cURL

curl -X GET "{{BASE_URL}}/api/contract-plans/{id}" \
  -H "api-key: {{API_KEY}}"

PowerShell

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

$response = Invoke-RestMethod -Method GET -Uri '{{BASE_URL}}/api/contract-plans/{id}' `
    -Headers $headers

npm install @winkpg/winkpg-api

TypeScript (SDK)

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

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

const { data } = await api.contractPlansGet("3fa85f64-5717-4562-b3fc-2c963f66afa6");

TypeScript (raw HTTP)

const response = await fetch('{{BASE_URL}}/api/contract-plans/{id}', {
  method: 'GET',
  headers: {
    "api-key": "{{API_KEY}}",
  },
});

const data = await response.json();

dotnet add package WinkPg.Api.Client

C# (SDK)

using WinkPg.Api.Client.Api;
using WinkPg.Api.Client.Client;

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

var api = new ContractPlansApi(config);
var result = await api.ContractPlansGetAsync(Guid.Parse("3fa85f64-5717-4562-b3fc-2c963f66afa6"));

C# (raw HTTP)

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

var request = new HttpRequestMessage(new HttpMethod("GET"), "/api/contract-plans/{id}");
request.Headers.Add("api-key", "{{API_KEY}}");

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.ContractPlansApi(client)
    result = api.contract_plans_get("3fa85f64-5717-4562-b3fc-2c963f66afa6")

pip install requests

Python (raw HTTP)

import requests

headers = {
    "api-key": "{{API_KEY}}",
}

response = requests.request(
    "GET",
    "{{BASE_URL}}/api/contract-plans/{id}",
    headers=headers,
)
response.raise_for_status()
data = response.json()

Parameters

Name In Type Description

id required

path

string (uuid)

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

suppressNulls required

query

boolean

If true, omit properties with null values.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Request body

application/json , required

Field	Type	Description

This request body has no documented fields.

Responses

200 OK

Body: ContractPlanDto ContractPlanDto Each item has these fields.

Field Type Description

id required

string (uuid)

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

creationTime required

string (date-time)

The date and time when this entity was created.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

creatorId required

string (uuid)

The ID of the user who created this entity. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

lastModificationTime required

string (date-time)

The date and time when this entity was last modified. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

lastModifierId required

string (uuid)

The ID of the user who last modified this entity. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

isDeleted required

boolean

Indicates whether this entity has been deleted.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

deleterId required

string (uuid)

The ID of the user who deleted this entity, if it is deleted. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

deletionTime required

string (date-time)

The date and time when this entity was deleted, if it is deleted. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

merchantId required

string (uuid)

The merchant that owns the plan.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

tenantId required

string (uuid)

The tenant that owns the plan. Null for host-level plans. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

name required

string

The plan's operator-facing name, unique within the owning merchant. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

code required

string

The merchant's own short code for the plan, or null. Not resolved by the platform. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

description required

string

What the plan covers, in the operator's own words. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

currencyCode required

string

The ISO 4217 alphabetic currency code the plan's amounts are denominated in. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

isActive required

boolean

Whether the plan may be subscribed to. An inactive plan keeps pricing the contracts already on it.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

defaultSchedule required

ContractSchedule ContractSchedule

The recurrence a new contract on this plan starts from, or null when the plan suggests none.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of ContractSchedule:

Field Type Description

frequency required

Frequency Frequency

The type of the recurrence rule.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

`Secondly`
`Minutely`
`Hourly`
`Daily`
`Weekly`
`Monthly`
`Yearly`

count required

integer (int32)

The number of occurrences in a particular recurrence. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

until required

string (date-time)

The datetime that bounds the current recurrence. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

interval required

integer (int32)

The recurrence interval.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

bySecond required

array of integer (int32) array of

BySecond rule modifier. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

byMinute required

array of integer (int32) array of

BySecond rule modifier. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

byHour required

array of integer (int32) array of

BySecond rule modifier. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

byDay required

array of ContractScheduleByDayRule array of ContractScheduleByDayRule

Week day rule modifier. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

byMonth required

array of integer (int32) array of

Month day rule modifier. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

byMonthDay required

array of integer (int32) array of

Month days rule modifier. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

byYearDay required

array of integer (int32) array of

Year days rule modifier. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

byWeekNumber required

array of integer (int32) array of

Week number rule modifier. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

bySetPosition required

array of integer (int32) array of

BySetPosition rule modifier. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

firstDayOfWeek required

DayOfWeek DayOfWeek

The first day of week, used in calculating weekday-based recurrences nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

`Sunday`
`Monday`
`Tuesday`
`Wednesday`
`Thursday`
`Friday`
`Saturday`

nextScheduledRun required

string (date-time)

The next computed billing date, updated after each billing run. Null for contracts that have never been scheduled or have ended. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

startDate required

string (date-time)

The earliest date on which this contract is eligible to bill. Set by the user when creating the contract (defaults to the creation date) and may be set to a future date to delay first billing. The recurrence engine anchors expansion to this date and the daily billing job will not fire a contract whose `startDate` is in the future. Null on contracts created before this field existed. When it is null, the server anchors the schedule on the contract's creation time, or on the current time when that is also absent; callers that compute a schedule themselves should apply the same fallback. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

trialDays required

integer (int32)

The trial length a new contract on this plan inherits, in days, or null when the plan offers no trial. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

currentPrice required

ContractPlanPriceDto ContractPlanPriceDto

The plan's price today: the revision in force at the moment the plan was read, with no scheduled run to measure a next-cycle change against.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of ContractPlanPriceDto:

Field Type Description

id required

string (uuid)

Identifies this revision.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

billSubtotalAmount required

number (double)

The base amount charged each cycle, before tax.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

taxAmount required

number (double)

The tax added to the base amount each cycle, or null when the plan carries no tax line. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

totalAmount required

number (double)

The total charged to the subscriber's payment method each cycle.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

effectiveFrom required

string (date-time)

The moment this revision starts applying, in UTC.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

policy required

ContractPlanPriceChangePolicy ContractPlanPriceChangePolicy

The propagation policy the revision was saved under.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

`Immediate`	The new price applies to every charge executed from the moment the change was saved, including a charge that was already due and has not run yet.
`NextCycle`	The new price applies only to charges that fall due after the change was saved. A charge that was already due when the price changed still bills at the old price, so a subscriber is never re-priced part-way through a cycle they have already entered.
`Scheduled`	The new price applies to charges executed on or after an operator-chosen effective moment. Until then every subscriber keeps billing at the previous price.

recordedAt required

string (date-time)

When the revision was saved, in UTC.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

recordedByUserId required

string (uuid)

The operator who saved the revision, or null when the platform wrote it. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

note required

string

Why the price changed, in the operator's own words. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

pendingPrice required

ContractPlanPriceDto ContractPlanPriceDto

The revision that will take over next, when one is scheduled and has not taken effect yet. Null when the plan has no pending change.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of ContractPlanPriceDto:

Field Type Description

id required

string (uuid)

Identifies this revision.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

billSubtotalAmount required

number (double)

The base amount charged each cycle, before tax.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

taxAmount required

number (double)

The tax added to the base amount each cycle, or null when the plan carries no tax line. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

totalAmount required

number (double)

The total charged to the subscriber's payment method each cycle.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

effectiveFrom required

string (date-time)

The moment this revision starts applying, in UTC.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

policy required

ContractPlanPriceChangePolicy ContractPlanPriceChangePolicy

The propagation policy the revision was saved under.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

`Immediate`	The new price applies to every charge executed from the moment the change was saved, including a charge that was already due and has not run yet.
`NextCycle`	The new price applies only to charges that fall due after the change was saved. A charge that was already due when the price changed still bills at the old price, so a subscriber is never re-priced part-way through a cycle they have already entered.
`Scheduled`	The new price applies to charges executed on or after an operator-chosen effective moment. Until then every subscriber keeps billing at the previous price.

recordedAt required

string (date-time)

When the revision was saved, in UTC.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

recordedByUserId required

string (uuid)

The operator who saved the revision, or null when the platform wrote it. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

note required

string

Why the price changed, in the operator's own words. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

prices required

array of ContractPlanPriceDto array of ContractPlanPriceDto

Every price the plan has carried, oldest first. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

Fields of each ContractPlanPriceDto:

Field Type Description

id required

string (uuid)

Identifies this revision.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

billSubtotalAmount required

number (double)

The base amount charged each cycle, before tax.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

taxAmount required

number (double)

The tax added to the base amount each cycle, or null when the plan carries no tax line. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

totalAmount required

number (double)

The total charged to the subscriber's payment method each cycle.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

effectiveFrom required

string (date-time)

The moment this revision starts applying, in UTC.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

policy required

ContractPlanPriceChangePolicy ContractPlanPriceChangePolicy

The propagation policy the revision was saved under.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

`Immediate`	The new price applies to every charge executed from the moment the change was saved, including a charge that was already due and has not run yet.
`NextCycle`	The new price applies only to charges that fall due after the change was saved. A charge that was already due when the price changed still bills at the old price, so a subscriber is never re-priced part-way through a cycle they have already entered.
`Scheduled`	The new price applies to charges executed on or after an operator-chosen effective moment. Until then every subscriber keeps billing at the previous price.

recordedAt required

string (date-time)

When the revision was saved, in UTC.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

recordedByUserId required

string (uuid)

The operator who saved the revision, or null when the platform wrote it. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

note required

string

Why the price changed, in the operator's own words. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This body has no documented fields.

concurrencyStamp required

string

The concurrency stamp used for optimistic concurrency control. nullable

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

entityVersion required

integer (int32)

The entity version, incremented on each modification.

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

403 Forbidden

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description

error required

RemoteServiceErrorInfo RemoteServiceErrorInfo

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

401 Unauthorized

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description

error required

RemoteServiceErrorInfo RemoteServiceErrorInfo

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

400 Bad Request

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description

error required

RemoteServiceErrorInfo RemoteServiceErrorInfo

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

404 Not Found

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description

error required

RemoteServiceErrorInfo RemoteServiceErrorInfo

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

501 Not Implemented

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description

error required

RemoteServiceErrorInfo RemoteServiceErrorInfo

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

500 Internal Server Error

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description

error required

RemoteServiceErrorInfo RemoteServiceErrorInfo

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

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. The error reference lists the values `error.code` can take. 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. The error reference lists the values `error.code` can take.

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description

error required

RemoteServiceErrorInfo RemoteServiceErrorInfo

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

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.

Body: RemoteServiceErrorResponse RemoteServiceErrorResponse Each item has these fields.

Field Type Description

error required

RemoteServiceErrorInfo RemoteServiceErrorInfo

Values: Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.

This response has no documented body fields.

Errors

A failed request returns the platform error envelope. The error reference lists every value error.code can carry and shows the four response shapes.

Codes declared by

The API reference isn't available right now

No such operation

This reference may be out of date

Get a ContractPlan

Example request

Parameters

Request body

Responses

200 OK

403 Forbidden

401 Unauthorized

400 Bad Request

404 Not Found

501 Not Implemented

500 Internal Server Error

Errors

Authentication