placements reference

This reference follows the current server implementation. Use the SDK for customer flows; it manages identity proof and retries. Authentication and errors apply to every endpoint. Types below describe JSON: dates are ISO strings, ? means optional, and null differs from an omitted field. Responses may include additional fields. Schemas also enforce constraints that TypeScript cannot express; download the request JSON Schemas. Named response types are defined in the data model reference.

POST /v1/placements/:identifier/evaluate

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Path parameters: identifier (string). Every target must belong to the authenticated app or workspace.

Request

Send JSON with Content-Type: application/json. Where multiple shapes are shown, the handler selects the applicable operation or validates nested input.

{ requestId: string;
  mode: "manual" | "automatic";
  }

unknown

{ paywall: { id: string;
  identifier: string;
  name: string;
  config: unknown;
  description?: string | null | undefined;
  };
  paywallProducts: { id: string;
  identifier: string;
  product: { id: string;
  identifier: string;
  name: string;
  pricingType: "subscription" | "non_consumable" | "consumable" | "free";
  pricingPeriod: "month" | "year" | null;
  description?: string | null | undefined;
  };
  productPrice: { id: string;
  provider: "stripe" | "apple_app_store" | "google_play" | "microsoft_store" | "custom";
  platform: "ios" | "android" | "web" | "windows" | "macos" | null;
  providerProductId: string;
  providerPriceId?: string | null | undefined;
  currency?: string | null | undefined;
  unitAmount?: number | null | undefined;
  billingPeriod?: "month" | "year" | null | undefined;
  trialOffer?: { type: "free_trial";
  trialPeriodDays?: number | undefined;
  appleSubscriptionGroupId?: string | undefined;
  } | null | undefined;
  } | null;
  prices?: Partial<Record<"stripe" | "apple_app_store" | "google_play" | "microsoft_store" | "custom", { amountMinor: number;
  currency: string;
  interval: "month" | "year" | null;
  intervalCount: number;
  }>> | undefined;
  }[];
  paywallOffers?: { identifier: string;
  productIdentifier: string;
  offerKind: "subscription_offer_code" | "in_app_purchase_offer_code";
  prices: { territory: string;
  pricePointId: string;
  customerPrice: string;
  currency: string;
  }[];
  offerMode?: "free" | "pay_as_you_go" | "pay_up_front" | "discount" | null | undefined;
  duration?: string | null | undefined;
  numberOfPeriods?: number | null | undefined;
  autoRenews?: boolean | null | undefined;
  regularPrice?: { amountMinor: number;
  currency: string;
  billingPeriod?: "month" | "year" | null | undefined;
  } | undefined;
  }[] | undefined;
  campaign?: { placementId: string;
  placementIdentifier: string;
  targetType: "paywall" | "in_app_surface" | "survey" | "custom" | "none";
  campaignId?: string | null | undefined;
  campaignIdentifier?: string | null | undefined;
  campaignAudienceId?: string | null | undefined;
  campaignAudienceIdentifier?: string | null | undefined;
  campaignVariantId?: string | null | undefined;
  campaignVariantIdentifier?: string | null | undefined;
  campaignAssignmentId?: string | null | undefined;
  } | undefined;
  }

Response

JSON response shape

{ id: string;
  identifier: string;
  targetType: string;
  }

JSON response shape

PlacementEvaluationResponse

JSON response shape

{ campaign?: { targetType: "none";
  placementId: string;
  placementIdentifier: string;
  campaignId?: string | null;
  campaignIdentifier?: string | null;
  campaignAudienceId?: string | null;
  campaignAudienceIdentifier?: string | null;
  campaignVariantId?: string | null;
  campaignVariantIdentifier?: string | null;
  campaignAssignmentId?: string | null;
  } | undefined;
  id: string;
  identifier: string;
  targetType: string;
  }

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handleEvaluatePlacement.

GET /v1/placements/:identifier/paywall

Authentication: Public or secret app API key; customer/session proof is still required wherever the operation acts on an identity.

Path parameters: identifier (string). Every target must belong to the authenticated app or workspace.

Request

Supply these values as query parameters. Path parameters remain in the URL.

"ios" | "android" | "web" | "windows" | "macos"

{ paywall: { id: string;
  identifier: string;
  name: string;
  config: unknown;
  description?: string | null | undefined;
  };
  paywallProducts: { id: string;
  identifier: string;
  product: { id: string;
  identifier: string;
  name: string;
  pricingType: "subscription" | "non_consumable" | "consumable" | "free";
  pricingPeriod: "month" | "year" | null;
  description?: string | null | undefined;
  };
  productPrice: { id: string;
  provider: "stripe" | "apple_app_store" | "google_play" | "microsoft_store" | "custom";
  platform: "ios" | "android" | "web" | "windows" | "macos" | null;
  providerProductId: string;
  providerPriceId?: string | null | undefined;
  currency?: string | null | undefined;
  unitAmount?: number | null | undefined;
  billingPeriod?: "month" | "year" | null | undefined;
  trialOffer?: { type: "free_trial";
  trialPeriodDays?: number | undefined;
  appleSubscriptionGroupId?: string | undefined;
  } | null | undefined;
  } | null;
  prices?: Partial<Record<"stripe" | "apple_app_store" | "google_play" | "microsoft_store" | "custom", { amountMinor: number;
  currency: string;
  interval: "month" | "year" | null;
  intervalCount: number;
  }>> | undefined;
  }[];
  paywallOffers?: { identifier: string;
  productIdentifier: string;
  offerKind: "subscription_offer_code" | "in_app_purchase_offer_code";
  prices: { territory: string;
  pricePointId: string;
  customerPrice: string;
  currency: string;
  }[];
  offerMode?: "free" | "pay_as_you_go" | "pay_up_front" | "discount" | null | undefined;
  duration?: string | null | undefined;
  numberOfPeriods?: number | null | undefined;
  autoRenews?: boolean | null | undefined;
  regularPrice?: { amountMinor: number;
  currency: string;
  billingPeriod?: "month" | "year" | null | undefined;
  } | undefined;
  }[] | undefined;
  campaign?: { placementId: string;
  placementIdentifier: string;
  targetType: "paywall" | "in_app_surface" | "survey" | "custom" | "none";
  campaignId?: string | null | undefined;
  campaignIdentifier?: string | null | undefined;
  campaignAudienceId?: string | null | undefined;
  campaignAudienceIdentifier?: string | null | undefined;
  campaignVariantId?: string | null | undefined;
  campaignVariantIdentifier?: string | null | undefined;
  campaignAssignmentId?: string | null | undefined;
  } | undefined;
  }

Response

JSON response shape

{ error: string;
  message: string;
  }

JSON response shape

PaywallResponse

Errors: validation/authentication failures use the common error envelope. A missing or inaccessible target returns an error; never interpret it as an empty successful result.

Implementation · Handler: handlePresentationPaywall.