Win-back offers
Read win-back offer information
Read win back offer information as a flat JSON object.
/win-back-offers/{winBackOfferId}Proposed · Extended read design · Adapter not implemented
Request
Routes are relative to your connection. Use a facade API key; the service manages Apple authentication.
BASE='https://asc.example.com/v1/connections/conn_example'
curl --fail-with-body "$BASE/win-back-offers/win_back_offer_123" \
-H "Authorization: Bearer $ASC_FACADE_KEY"const base = "https://asc.example.com/v1/connections/conn_example";
const response = await fetch(`${base}/win-back-offers/win_back_offer_123`, {
headers: { Authorization: `Bearer ${process.env.ASC_FACADE_KEY}` }
});
const body = await response.json();
if (!response.ok) {
throw new Error(body.error?.message ?? `HTTP ${response.status}`);
}
console.log(body);import json
import os
from urllib.request import Request, urlopen
from urllib.error import HTTPError
base = "https://asc.example.com/v1/connections/conn_example"
request = Request(
f"{base}/win-back-offers/win_back_offer_123",
headers={"Authorization": f"Bearer {os.environ['ASC_FACADE_KEY']}"},
)
try:
with urlopen(request) as response:
print(json.load(response))
except HTTPError as error:
detail = json.load(error)
raise RuntimeError(detail["error"]["message"]) from errorasc.example.com is a placeholder for your deployment. Examples use fictional IDs.
Path parameters
| Name | Type | Description |
|---|---|---|
| winBackOfferId | string | The selected resource’s ID. |
Query parameters
| Name | Type | Description |
|---|---|---|
| fields | string | Comma-separated attribute names to return. This selects read fields and does not expand relationships. Multiple values are comma-separated.ValuesreferenceName, offerId, duration, offerMode, periodCount, customerEligibilityPaidSubscriptionDurationInMonths, customerEligibilityTimeSinceLastSubscribedInMonths, customerEligibilityWaitBetweenOffersInMonths, startDate, endDate, priority, promotionIntent, targetSubscriptionPlanType |
Response
One flat object for the selected resource.
{
"id": "win_back_offer_123",
"referenceName": "Example subscription",
"offerId": "offer_123",
"duration": "THREE_DAYS",
"offerMode": "PAY_AS_YOU_GO",
"periodCount": 1
}Illustrative response. Optional read fields may be absent or null; unknown enum values are preserved.
Response fields
| Name | Type | Description |
|---|---|---|
| id | string | Apple’s resource ID. Keep this string unchanged when addressing a resource. |
| referenceName | string | The internal reference name configured for this resource. |
| offerId | string | The ID of the selected offer. |
| duration | string | The duration value reported by Apple for this resource.ValuesTHREE_DAYS, ONE_WEEK, TWO_WEEKS, ONE_MONTH, TWO_MONTHS, THREE_MONTHS, SIX_MONTHS, ONE_YEAR |
| offerMode | string | The offer mode value reported by Apple for this resource.ValuesPAY_AS_YOU_GO, PAY_UP_FRONT, FREE_TRIAL |
| periodCount | integer | The period count value reported by Apple for this resource. |
| customerEligibilityPaidSubscriptionDurationInMonths | integer | The customer eligibility paid subscription duration in months value reported by Apple for this resource. |
| customerEligibilityTimeSinceLastSubscribedInMonths | object | The customer eligibility time since last subscribed in months value reported by Apple for this resource. |
| customerEligibilityWaitBetweenOffersInMonths | integer | The customer eligibility wait between offers in months value reported by Apple for this resource. |
| startDate | string · date | The beginning of this resource’s scheduled period. |
| endDate | string · date | The end of this resource’s scheduled period. |
| priority | string | The priority value reported by Apple for this resource.ValuesHIGH, NORMAL |
| promotionIntent | string | The promotion intent value reported by Apple for this resource.ValuesNOT_PROMOTED, USE_AUTO_GENERATED_ASSETS |
| targetSubscriptionPlanType | string | The target subscription plan type value reported by Apple for this resource.ValuesMONTHLY, UPFRONT |
customerEligibilityTimeSinceLastSubscribedInMonths fields
| Name | Type | Description |
|---|---|---|
| minimum | integer | The minimum value reported by Apple for this resource. |
| maximum | integer | The maximum value reported by Apple for this resource. |
Behavior
- A nested resource must belong to the selected parent and the configured connection. The adapter validates ownership before returning data.
Errors
| HTTP | Type | Description |
|---|---|---|
| 400 | invalid_query | Unsupported filter, sort, limit, or cursor. |
| 401 | unauthorized | Missing or invalid facade API key. |
| 403 | forbidden / upstream_forbidden | The caller or configured Apple key cannot read this resource. |
| 404 | resource_not_found | The requested resource, parent, or exact locale is absent or outside the caller’s scope. |
| 429 | rate_limited | A facade or Apple rate limit was reached. Respect Retry-After when returned. |
| 502–504 | upstream error | Apple authentication, response parsing, availability, or timeout failure; this is not an empty result. |
Apple mapping
Upstream route and translation
The adapter calls GET /v1/winBackOffers/{id}. Read Apple’s original endpoint ↗
Flatten Apple’s attributes into each resource object. Expose supplied singleton linkage as IDs, with no automatic relationship traversal. Read access does not make these fields writable.
| Facade parameter | Type | Description |
|---|---|---|
| fields | query | fields[winBackOffers] |
Reviewed 2026-10-14 · OpenAPI 4.5.1