openapi: 3.0.1 info: title: App Store Connect AccessibilityDeclarations SubscriptionPromotionalOffers API version: 4.3.1 x-platforms: app_store_connect_api: App Store Connect API description: The App Store Connect API is the standards-based REST API Apple provides to automate tasks across App Store Connect, Xcode, and Certificates, Identifiers & Profiles. It covers apps, builds, TestFlight, in-app purchases, subscriptions, Game Center, Xcode Cloud, provisioning, pricing and availability, and the full reporting surface (analytics, sales and trends, financial reports, power and performance). This spec is the official OpenAPI 3.0 document published by Apple at https://developer.apple.com/app-store-connect/api/ — mirrored here unmodified except for title-cased operation summaries. servers: - url: https://api.appstoreconnect.apple.com/ security: - itc-bearer-token: [] tags: - name: SubscriptionPromotionalOffers paths: /v1/subscriptionPromotionalOffers: post: tags: - SubscriptionPromotionalOffers operationId: subscriptionPromotionalOffers_createInstance requestBody: description: SubscriptionPromotionalOffer representation content: application/json: schema: $ref: '#/components/schemas/SubscriptionPromotionalOfferCreateRequest' required: true responses: '400': description: Parameter error(s) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized error(s) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Unprocessable request entity error(s) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '201': description: Single SubscriptionPromotionalOffer content: application/json: schema: $ref: '#/components/schemas/SubscriptionPromotionalOfferResponse' '409': description: Request entity error(s) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Rate limit exceeded error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Create Subscription Promotional Offers /v1/subscriptionPromotionalOffers/{id}: parameters: - name: id in: path description: the id of the requested resource schema: type: string style: simple required: true get: tags: - SubscriptionPromotionalOffers operationId: subscriptionPromotionalOffers_getInstance parameters: - name: fields[subscriptionPromotionalOffers] in: query description: the fields to include for returned resources of type subscriptionPromotionalOffers schema: type: array items: type: string enum: - duration - name - numberOfPeriods - offerCode - offerMode - subscription - prices style: form explode: false required: false - name: fields[subscriptions] in: query description: the fields to include for returned resources of type subscriptions schema: type: array items: type: string enum: - name - productId - familySharable - state - subscriptionPeriod - reviewNote - groupLevel - subscriptionLocalizations - appStoreReviewScreenshot - group - introductoryOffers - promotionalOffers - offerCodes - prices - pricePoints - promotedPurchase - subscriptionAvailability - winBackOffers - images style: form explode: false required: false - name: fields[subscriptionPromotionalOfferPrices] in: query description: the fields to include for returned resources of type subscriptionPromotionalOfferPrices schema: type: array items: type: string enum: - territory - subscriptionPricePoint style: form explode: false required: false - name: include in: query description: comma-separated list of relationships to include schema: type: array items: type: string enum: - subscription - prices style: form explode: false required: false - name: limit[prices] in: query description: maximum number of related prices returned (when they are included) schema: type: integer maximum: 50 style: form required: false responses: '400': description: Parameter error(s) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized error(s) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '200': description: Single SubscriptionPromotionalOffer content: application/json: schema: $ref: '#/components/schemas/SubscriptionPromotionalOfferResponse' '429': description: Rate limit exceeded error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Get Subscription Promotional Offers patch: tags: - SubscriptionPromotionalOffers operationId: subscriptionPromotionalOffers_updateInstance requestBody: description: SubscriptionPromotionalOffer representation content: application/json: schema: $ref: '#/components/schemas/SubscriptionPromotionalOfferUpdateRequest' required: true responses: '400': description: Parameter error(s) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized error(s) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Unprocessable request entity error(s) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '200': description: Single SubscriptionPromotionalOffer content: application/json: schema: $ref: '#/components/schemas/SubscriptionPromotionalOfferResponse' '409': description: Request entity error(s) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Rate limit exceeded error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Update Subscription Promotional Offers delete: tags: - SubscriptionPromotionalOffers operationId: subscriptionPromotionalOffers_deleteInstance responses: '400': description: Parameter error(s) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized error(s) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '204': description: Success (no content) '429': description: Rate limit exceeded error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Delete Subscription Promotional Offers /v1/subscriptionPromotionalOffers/{id}/relationships/prices: parameters: - name: id in: path description: the id of the requested resource schema: type: string style: simple required: true get: tags: - SubscriptionPromotionalOffers operationId: subscriptionPromotionalOffers_prices_getToManyRelationship parameters: - name: limit in: query description: maximum resources per page schema: type: integer maximum: 200 style: form responses: '400': description: Parameter error(s) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized error(s) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '200': description: List of related linkages content: application/json: schema: $ref: '#/components/schemas/SubscriptionPromotionalOfferPricesLinkagesResponse' '429': description: Rate limit exceeded error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: List Related Subscription Promotional Offers / Prices /v1/subscriptionPromotionalOffers/{id}/prices: parameters: - name: id in: path description: the id of the requested resource schema: type: string style: simple required: true get: tags: - SubscriptionPromotionalOffers operationId: subscriptionPromotionalOffers_prices_getToManyRelated parameters: - name: filter[territory] in: query description: filter by id(s) of related 'territory' schema: type: array items: type: string style: form explode: false - name: fields[subscriptionPromotionalOfferPrices] in: query description: the fields to include for returned resources of type subscriptionPromotionalOfferPrices schema: type: array items: type: string enum: - territory - subscriptionPricePoint style: form explode: false - name: fields[territories] in: query description: the fields to include for returned resources of type territories schema: type: array items: type: string enum: - currency style: form explode: false - name: fields[subscriptionPricePoints] in: query description: the fields to include for returned resources of type subscriptionPricePoints schema: type: array items: type: string enum: - customerPrice - proceeds - proceedsYear2 - territory - equalizations style: form explode: false - name: limit in: query description: maximum resources per page schema: type: integer maximum: 200 style: form - name: include in: query description: comma-separated list of relationships to include schema: type: array items: type: string enum: - territory - subscriptionPricePoint style: form explode: false responses: '400': description: Parameter error(s) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized error(s) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '200': description: List of SubscriptionPromotionalOfferPrices content: application/json: schema: $ref: '#/components/schemas/SubscriptionPromotionalOfferPricesResponse' '429': description: Rate limit exceeded error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: List Related Subscription Promotional Offers / Prices components: schemas: PagedDocumentLinks: type: object properties: self: type: string format: uri-reference first: type: string format: uri-reference next: type: string format: uri-reference required: - self SubscriptionOfferMode: type: string enum: - PAY_AS_YOU_GO - PAY_UP_FRONT - FREE_TRIAL SubscriptionOfferDuration: type: string enum: - THREE_DAYS - ONE_WEEK - TWO_WEEKS - ONE_MONTH - TWO_MONTHS - THREE_MONTHS - SIX_MONTHS - ONE_YEAR ResourceLinks: type: object properties: self: type: string format: uri-reference ErrorSourceParameter: type: object title: Parameter properties: parameter: type: string required: - parameter ErrorLinks: type: object properties: about: type: string format: uri-reference associated: oneOf: - type: string format: uri-reference - type: object properties: href: type: string format: uri-reference meta: type: object properties: source: type: string SubscriptionPromotionalOffer: type: object title: SubscriptionPromotionalOffer properties: type: type: string enum: - subscriptionPromotionalOffers id: type: string attributes: type: object properties: duration: $ref: '#/components/schemas/SubscriptionOfferDuration' name: type: string numberOfPeriods: type: integer offerCode: type: string offerMode: $ref: '#/components/schemas/SubscriptionOfferMode' relationships: type: object properties: subscription: type: object properties: data: type: object properties: type: type: string enum: - subscriptions id: type: string required: - id - type prices: type: object properties: links: $ref: '#/components/schemas/RelationshipLinks' meta: $ref: '#/components/schemas/PagingInformation' data: type: array items: type: object properties: type: type: string enum: - subscriptionPromotionalOfferPrices id: type: string required: - id - type links: $ref: '#/components/schemas/ResourceLinks' required: - id - type SubscriptionPricePoint: type: object title: SubscriptionPricePoint properties: type: type: string enum: - subscriptionPricePoints id: type: string attributes: type: object properties: customerPrice: type: string proceeds: type: string proceedsYear2: type: string relationships: type: object properties: territory: type: object properties: data: type: object properties: type: type: string enum: - territories id: type: string required: - id - type equalizations: type: object properties: links: $ref: '#/components/schemas/RelationshipLinks' links: $ref: '#/components/schemas/ResourceLinks' required: - id - type DocumentLinks: type: object properties: self: type: string format: uri-reference required: - self SubscriptionPromotionalOfferResponse: type: object title: SubscriptionPromotionalOfferResponse properties: data: $ref: '#/components/schemas/SubscriptionPromotionalOffer' included: type: array items: oneOf: - $ref: '#/components/schemas/SubscriptionPromotionalOfferPrice' - $ref: '#/components/schemas/Subscription' discriminator: propertyName: type mapping: subscriptions: '#/components/schemas/Subscription' subscriptionPromotionalOfferPrices: '#/components/schemas/SubscriptionPromotionalOfferPrice' links: $ref: '#/components/schemas/DocumentLinks' required: - data - links SubscriptionPromotionalOfferPricesResponse: type: object title: SubscriptionPromotionalOfferPricesResponse properties: data: type: array items: $ref: '#/components/schemas/SubscriptionPromotionalOfferPrice' included: type: array items: oneOf: - $ref: '#/components/schemas/SubscriptionPricePoint' - $ref: '#/components/schemas/Territory' discriminator: propertyName: type mapping: territories: '#/components/schemas/Territory' subscriptionPricePoints: '#/components/schemas/SubscriptionPricePoint' links: $ref: '#/components/schemas/PagedDocumentLinks' meta: $ref: '#/components/schemas/PagingInformation' required: - data - links ErrorResponse: type: object properties: errors: type: array items: type: object properties: id: type: string status: type: string code: type: string title: type: string detail: type: string source: oneOf: - $ref: '#/components/schemas/ErrorSourcePointer' - $ref: '#/components/schemas/ErrorSourceParameter' links: $ref: '#/components/schemas/ErrorLinks' meta: type: object additionalProperties: {} required: - code - detail - status - title SubscriptionPromotionalOfferPrice: type: object title: SubscriptionPromotionalOfferPrice properties: type: type: string enum: - subscriptionPromotionalOfferPrices id: type: string relationships: type: object properties: territory: type: object properties: data: type: object properties: type: type: string enum: - territories id: type: string required: - id - type subscriptionPricePoint: type: object properties: data: type: object properties: type: type: string enum: - subscriptionPricePoints id: type: string required: - id - type links: $ref: '#/components/schemas/ResourceLinks' required: - id - type SubscriptionPromotionalOfferCreateRequest: type: object title: SubscriptionPromotionalOfferCreateRequest properties: data: type: object properties: type: type: string enum: - subscriptionPromotionalOffers attributes: type: object properties: duration: $ref: '#/components/schemas/SubscriptionOfferDuration' name: type: string numberOfPeriods: type: integer offerCode: type: string offerMode: $ref: '#/components/schemas/SubscriptionOfferMode' required: - duration - offerCode - name - numberOfPeriods - offerMode relationships: type: object properties: subscription: type: object properties: data: type: object properties: type: type: string enum: - subscriptions id: type: string required: - id - type required: - data prices: type: object properties: data: type: array items: type: object properties: type: type: string enum: - subscriptionPromotionalOfferPrices id: type: string required: - id - type required: - data required: - subscription - prices required: - relationships - attributes - type included: type: array items: $ref: '#/components/schemas/SubscriptionPromotionalOfferPriceInlineCreate' required: - data SubscriptionPromotionalOfferUpdateRequest: type: object title: SubscriptionPromotionalOfferUpdateRequest properties: data: type: object properties: type: type: string enum: - subscriptionPromotionalOffers id: type: string relationships: type: object properties: prices: type: object properties: data: type: array items: type: object properties: type: type: string enum: - subscriptionPromotionalOfferPrices id: type: string required: - id - type required: - id - type included: type: array items: $ref: '#/components/schemas/SubscriptionPromotionalOfferPriceInlineCreate' required: - data RelationshipLinks: type: object properties: self: type: string format: uri-reference related: type: string format: uri-reference ErrorSourcePointer: type: object title: JsonPointer properties: pointer: type: string required: - pointer SubscriptionPromotionalOfferPricesLinkagesResponse: type: object properties: data: type: array items: type: object properties: type: type: string enum: - subscriptionPromotionalOfferPrices id: type: string required: - id - type links: $ref: '#/components/schemas/PagedDocumentLinks' meta: $ref: '#/components/schemas/PagingInformation' required: - data - links PagingInformation: type: object properties: paging: type: object properties: total: type: integer limit: type: integer nextCursor: type: string required: - limit required: - paging Subscription: type: object title: Subscription properties: type: type: string enum: - subscriptions id: type: string attributes: type: object properties: name: type: string productId: type: string familySharable: type: boolean state: type: string enum: - MISSING_METADATA - READY_TO_SUBMIT - WAITING_FOR_REVIEW - IN_REVIEW - DEVELOPER_ACTION_NEEDED - PENDING_BINARY_APPROVAL - APPROVED - DEVELOPER_REMOVED_FROM_SALE - REMOVED_FROM_SALE - REJECTED subscriptionPeriod: type: string enum: - ONE_WEEK - ONE_MONTH - TWO_MONTHS - THREE_MONTHS - SIX_MONTHS - ONE_YEAR reviewNote: type: string groupLevel: type: integer relationships: type: object properties: subscriptionLocalizations: type: object properties: links: $ref: '#/components/schemas/RelationshipLinks' meta: $ref: '#/components/schemas/PagingInformation' data: type: array items: type: object properties: type: type: string enum: - subscriptionLocalizations id: type: string required: - id - type appStoreReviewScreenshot: type: object properties: links: $ref: '#/components/schemas/RelationshipLinks' data: type: object properties: type: type: string enum: - subscriptionAppStoreReviewScreenshots id: type: string required: - id - type group: type: object properties: data: type: object properties: type: type: string enum: - subscriptionGroups id: type: string required: - id - type introductoryOffers: type: object properties: links: $ref: '#/components/schemas/RelationshipLinks' meta: $ref: '#/components/schemas/PagingInformation' data: type: array items: type: object properties: type: type: string enum: - subscriptionIntroductoryOffers id: type: string required: - id - type promotionalOffers: type: object properties: links: $ref: '#/components/schemas/RelationshipLinks' meta: $ref: '#/components/schemas/PagingInformation' data: type: array items: type: object properties: type: type: string enum: - subscriptionPromotionalOffers id: type: string required: - id - type offerCodes: type: object properties: links: $ref: '#/components/schemas/RelationshipLinks' meta: $ref: '#/components/schemas/PagingInformation' data: type: array items: type: object properties: type: type: string enum: - subscriptionOfferCodes id: type: string required: - id - type prices: type: object properties: links: $ref: '#/components/schemas/RelationshipLinks' meta: $ref: '#/components/schemas/PagingInformation' data: type: array items: type: object properties: type: type: string enum: - subscriptionPrices id: type: string required: - id - type pricePoints: type: object properties: links: $ref: '#/components/schemas/RelationshipLinks' promotedPurchase: type: object properties: links: $ref: '#/components/schemas/RelationshipLinks' data: type: object properties: type: type: string enum: - promotedPurchases id: type: string required: - id - type subscriptionAvailability: type: object properties: links: $ref: '#/components/schemas/RelationshipLinks' data: type: object properties: type: type: string enum: - subscriptionAvailabilities id: type: string required: - id - type winBackOffers: type: object properties: links: $ref: '#/components/schemas/RelationshipLinks' meta: $ref: '#/components/schemas/PagingInformation' data: type: array items: type: object properties: type: type: string enum: - winBackOffers id: type: string required: - id - type images: type: object properties: links: $ref: '#/components/schemas/RelationshipLinks' meta: $ref: '#/components/schemas/PagingInformation' data: type: array items: type: object properties: type: type: string enum: - subscriptionImages id: type: string required: - id - type links: $ref: '#/components/schemas/ResourceLinks' required: - id - type Territory: type: object title: Territory properties: type: type: string enum: - territories id: type: string attributes: type: object properties: currency: type: string links: $ref: '#/components/schemas/ResourceLinks' required: - id - type SubscriptionPromotionalOfferPriceInlineCreate: type: object properties: type: type: string enum: - subscriptionPromotionalOfferPrices id: type: string relationships: type: object properties: territory: type: object properties: data: type: object properties: type: type: string enum: - territories id: type: string required: - id - type subscriptionPricePoint: type: object properties: data: type: object properties: type: type: string enum: - subscriptionPricePoints id: type: string required: - id - type required: - type securitySchemes: itc-bearer-token: type: http scheme: bearer bearerFormat: JWT