appstoreserverlibrary.api_client module¶

An error that indicates the server didn’t find a subscription-renewal-date extension request for the request identifier and product identifier you provided.

https://developer.apple.com/documentation/appstoreserverapi/statusrequestnotfounderror

SUBSCRIPTION_EXTENSION_INELIGIBLE = 4030004¶

An error that indicates the subscription doesn’t qualify for a renewal-date extension due to its subscription state.

https://developer.apple.com/documentation/appstoreserverapi/subscriptionextensionineligibleerror

SUBSCRIPTION_MAX_EXTENSION = 4030005¶

An error that indicates the subscription doesn’t qualify for a renewal-date extension because it has already received the maximum extensions.

https://developer.apple.com/documentation/appstoreserverapi/subscriptionmaxextensionerror

TEST_NOTIFICATION_NOT_FOUND = 4040008¶

An error that indicates that the test notification token is expired or the test notification status isn’t available.

https://developer.apple.com/documentation/appstoreserverapi/testnotificationnotfounderror

TRANSACTION_ID_IS_NOT_ORIGINAL_TRANSACTION_ID_ERROR = 4000187¶

An error that indicates the endpoint expects an original transaction identifier.

https://developer.apple.com/documentation/appstoreserverapi/transactionidisnotoriginaltransactioniderror

TRANSACTION_ID_NOT_FOUND = 4040010¶

An error that indicates a transaction identifier wasn’t found.

https://developer.apple.com/documentation/appstoreserverapi/transactionidnotfounderror

exception appstoreserverlibrary.api_client.APIException(http_status_code: int, raw_api_error: int | None = None, error_message: str | None = None)[source]¶

Bases: Exception

api_error: APIError | None¶

error_message: str | None¶

http_status_code: int¶

raw_api_error: int | None¶

class appstoreserverlibrary.api_client.AppStoreServerAPIClient(signing_key: bytes, key_id: str, issuer_id: str, bundle_id: str, environment: Environment)[source]¶

Bases: BaseAppStoreServerAPIClient

configure_default_message(product_id: str, locale: str, default_configuration_request: DefaultConfigurationRequest)[source]¶

Configure a default message for a specific product in a specific locale.

Parameters:

product_id – The product identifier for the default configuration.
locale – The locale for the default configuration.
default_configuration_request – The request body that includes the message identifier to configure as the default message.

Raises:

APIException – If a response was returned indicating the request could not be processed

See:

https://developer.apple.com/documentation/retentionmessaging/configure-default-message

delete_default_message(product_id: str, locale: str)[source]¶

Delete a default message for a product in a locale.

Parameters:

product_id – The product ID of the default message configuration.
locale – The locale of the default message configuration.

Raises:

APIException – If a response was returned indicating the request could not be processed

See:

https://developer.apple.com/documentation/retentionmessaging/delete-default-message

delete_image(image_identifier: UUID)[source]¶

Delete a previously uploaded image.

Parameters:: image_identifier – The identifier of the image to delete.
Raises:: APIException – If a response was returned indicating the request could not be processed
See:: https://developer.apple.com/documentation/retentionmessaging/delete-image

delete_message(message_identifier: UUID)[source]¶

Delete a previously uploaded message.

Parameters:: message_identifier – The identifier of the message to delete.
Raises:: APIException – If a response was returned indicating the request could not be processed
See:: https://developer.apple.com/documentation/retentionmessaging/delete-message

extend_renewal_date_for_all_active_subscribers(mass_extend_renewal_date_request: MassExtendRenewalDateRequest) → MassExtendRenewalDateResponse[source]¶

Uses a subscription’s product identifier to extend the renewal date for all of its eligible active subscribers. https://developer.apple.com/documentation/appstoreserverapi/extend_subscription_renewal_dates_for_all_active_subscribers

Parameters:: mass_extend_renewal_date_request – The request body for extending a subscription renewal date for all of its active subscribers.
Returns:: A response that indicates the server successfully received the subscription-renewal-date extension request.
Throws APIException:: If a response was returned indicating the request could not be processed

extend_subscription_renewal_date(original_transaction_id: str, extend_renewal_date_request: ExtendRenewalDateRequest) → ExtendRenewalDateResponse[source]¶

Extends the renewal date of a customer’s active subscription using the original transaction identifier. https://developer.apple.com/documentation/appstoreserverapi/extend_a_subscription_renewal_date

Parameters:

original_transaction_id – The original transaction identifier of the subscription receiving a renewal date extension.
extend_renewal_date_request – The request body containing subscription-renewal-extension data.

Returns:

A response that indicates whether an individual renewal-date extension succeeded, and related details.

Throws APIException:

If a response was returned indicating the request could not be processed

get_all_subscription_statuses(transaction_id: str, status: List[Status] | None = None) → StatusResponse[source]¶

Get the statuses for all of a customer’s auto-renewable subscriptions in your app. https://developer.apple.com/documentation/appstoreserverapi/get_all_subscription_statuses

Parameters:

transaction_id – The identifier of a transaction that belongs to the customer, and which may be an original transaction identifier.
status – An optional filter that indicates the status of subscriptions to include in the response. Your query may specify more than one status query parameter.

Returns:

A response that contains status information for all of a customer’s auto-renewable subscriptions in your app.

Throws APIException:

If a response was returned indicating the request could not be processed

get_app_transaction_info(transaction_id: str) → AppTransactionInfoResponse[source]¶

Get a customer’s app transaction information for your app.

:param transaction_id Any originalTransactionId, transactionId or appTransactionId that belongs to the customer for your app. :return: A response that contains signed app transaction information for a customer. :raises APIException: If a response was returned indicating the request could not be processed :see: https://developer.apple.com/documentation/appstoreserverapi/get-app-transaction-info

get_image_list() → GetImageListResponse[source]¶

Get the image identifier and state for all uploaded images.

Returns:: A response that contains status information for all images.
Raises:: APIException – If a response was returned indicating the request could not be processed
See:: https://developer.apple.com/documentation/retentionmessaging/get-image-list

get_message_list() → GetMessageListResponse[source]¶

Get the message identifier and state of all uploaded messages.

Returns:: A response that contains status information for all messages.
Raises:: APIException – If a response was returned indicating the request could not be processed
See:: https://developer.apple.com/documentation/retentionmessaging/get-message-list

get_notification_history(pagination_token: str | None, notification_history_request: NotificationHistoryRequest) → NotificationHistoryResponse[source]¶

Get a list of notifications that the App Store server attempted to send to your server. https://developer.apple.com/documentation/appstoreserverapi/get_notification_history

Parameters:

pagination_token – An optional token you use to get the next set of up to 20 notification history records. All responses that have more records available include a paginationToken. Omit this parameter the first time you call this endpoint.
notification_history_request – The request body that includes the start and end dates, and optional query constraints.

Returns:

A response that contains the App Store Server Notifications history for your app.

Throws APIException:

If a response was returned indicating the request could not be processed

get_refund_history(transaction_id: str, revision: str | None) → RefundHistoryResponse[source]¶

Get a paginated list of all of a customer’s refunded in-app purchases for your app. https://developer.apple.com/documentation/appstoreserverapi/get_refund_history

Parameters:

transaction_id – The identifier of a transaction that belongs to the customer, and which may be an original transaction identifier.
revision – A token you provide to get the next set of up to 20 transactions. All responses include a revision token. Use the revision token from the previous RefundHistoryResponse.

Returns:

A response that contains status information for all of a customer’s auto-renewable subscriptions in your app.

Throws APIException:

If a response was returned indicating the request could not be processed

get_status_of_subscription_renewal_date_extensions(request_identifier: str, product_id: str) → MassExtendRenewalDateStatusResponse[source]¶

Checks whether a renewal date extension request completed, and provides the final count of successful or failed extensions. https://developer.apple.com/documentation/appstoreserverapi/get_status_of_subscription_renewal_date_extensions

Parameters:

request_identifier – The UUID that represents your request to the Extend Subscription Renewal Dates for All Active Subscribers endpoint.
product_id – The product identifier of the auto-renewable subscription that you request a renewal-date extension for.

Returns:

A response that indicates the current status of a request to extend the subscription renewal date to all eligible subscribers.

Throws APIException:

If a response was returned indicating the request could not be processed

get_test_notification_status(test_notification_token: str) → CheckTestNotificationResponse[source]¶

Check the status of the test App Store server notification sent to your server. https://developer.apple.com/documentation/appstoreserverapi/get_test_notification_status

Parameters:: test_notification_token – The test notification token received from the Request a Test Notification endpoint
Returns:: A response that contains the contents of the test notification sent by the App Store server and the result from your server.
Throws APIException:: If a response was returned indicating the request could not be processed

get_transaction_history(transaction_id: str, revision: str | None, transaction_history_request: TransactionHistoryRequest, version: GetTransactionHistoryVersion = GetTransactionHistoryVersion.V1) → HistoryResponse[source]¶

Get a customer’s in-app purchase transaction history for your app. https://developer.apple.com/documentation/appstoreserverapi/get_transaction_history

Parameters:

transaction_id – The identifier of a transaction that belongs to the customer, and which may be an original transaction identifier.
revision – A token you provide to get the next set of up to 20 transactions. All responses include a revision token. Note: For requests that use the revision token, include the same query parameters from the initial request. Use the revision token from the previous HistoryResponse.
transaction_history_request – The request parameters that includes the startDate,endDate,productIds,productTypes and optional query constraints.
version – The version of the Get Transaction History endpoint to use. V2 is recommended.

Returns:

A response that contains the customer’s transaction history for an app.

Throws APIException:

If a response was returned indicating the request could not be processed

get_transaction_info(transaction_id: str) → TransactionInfoResponse[source]¶

Get information about a single transaction for your app. https://developer.apple.com/documentation/appstoreserverapi/get_transaction_info

:param transaction_id The identifier of a transaction that belongs to the customer, and which may be an original transaction identifier. :return: A response that contains signed transaction information for a single transaction. :throws APIException: If a response was returned indicating the request could not be processed

look_up_order_id(order_id: str) → OrderLookupResponse[source]¶

Get a customer’s in-app purchases from a receipt using the order ID. https://developer.apple.com/documentation/appstoreserverapi/look_up_order_id

Parameters:: order_id – The order ID for in-app purchases that belong to the customer.
Returns:: A response that includes the order lookup status and an array of signed transactions for the in-app purchases in the order.
Throws APIException:: If a response was returned indicating the request could not be processed

request_test_notification() → SendTestNotificationResponse[source]¶

Ask App Store Server Notifications to send a test notification to your server. https://developer.apple.com/documentation/appstoreserverapi/request_a_test_notification

Returns:: A response that contains the test notification token.
Throws APIException:: If a response was returned indicating the request could not be processed

send_consumption_data(transaction_id: str, consumption_request: ConsumptionRequest)[source]¶

Send consumption information about a consumable in-app purchase to the App Store after your server receives a consumption request notification. https://developer.apple.com/documentation/appstoreserverapi/send_consumption_information

Parameters:

transaction_id – The transaction identifier for which you’re providing consumption information. You receive this identifier in the CONSUMPTION_REQUEST notification the App Store sends to your server.
consumption_request – The request body containing consumption information.

Raises:

APIException – If a response was returned indicating the request could not be processed

set_app_account_token(original_transaction_id: str, update_app_account_token_request: UpdateAppAccountTokenRequest)[source]¶

Sets the app account token value for a purchase the customer makes outside your app, or updates its value in an existing transaction. https://developer.apple.com/documentation/appstoreserverapi/set-app-account-token

:param original_transaction_id The original transaction identifier of the transaction to receive the app account token update. :param update_app_account_token_request The request body that contains a valid app account token value. :raises APIException: If a response was returned indicating the request could not be processed

upload_image(image_identifier: UUID, image: bytes)[source]¶

Upload an image to use for retention messaging.

Parameters:

image_identifier – A UUID you provide to uniquely identify the image you upload.
image – The image file to upload.

Raises:

APIException – If a response was returned indicating the request could not be processed

See:

https://developer.apple.com/documentation/retentionmessaging/upload-image

upload_message(message_identifier: UUID, upload_message_request_body: UploadMessageRequestBody)[source]¶

Upload a message to use for retention messaging.

Parameters:

message_identifier – A UUID you provide to uniquely identify the message you upload.
upload_message_request_body – The message text to upload.

Raises:

APIException – If a response was returned indicating the request could not be processed

See:

https://developer.apple.com/documentation/retentionmessaging/upload-message

class appstoreserverlibrary.api_client.AsyncAppStoreServerAPIClient(signing_key: bytes, key_id: str, issuer_id: str, bundle_id: str, environment: Environment)[source]¶

Bases: BaseAppStoreServerAPIClient

async async_close()[source]¶

async configure_default_message(product_id: str, locale: str, default_configuration_request: DefaultConfigurationRequest)[source]¶

Configure a default message for a specific product in a specific locale.

Parameters:

product_id – The product identifier for the default configuration.
locale – The locale for the default configuration.
default_configuration_request – The request body that includes the message identifier to configure as the default message.

Raises:

APIException – If a response was returned indicating the request could not be processed

See:

https://developer.apple.com/documentation/retentionmessaging/configure-default-message

async delete_default_message(product_id: str, locale: str)[source]¶

Delete a default message for a product in a locale.

Parameters:

product_id – The product ID of the default message configuration.
locale – The locale of the default message configuration.

Raises:

APIException – If a response was returned indicating the request could not be processed

See:

https://developer.apple.com/documentation/retentionmessaging/delete-default-message

async delete_image(image_identifier: UUID)[source]¶

Delete a previously uploaded image.

Parameters:: image_identifier – The identifier of the image to delete.
Raises:: APIException – If a response was returned indicating the request could not be processed
See:: https://developer.apple.com/documentation/retentionmessaging/delete-image

async delete_message(message_identifier: UUID)[source]¶

Delete a previously uploaded message.

Parameters:: message_identifier – The identifier of the message to delete.
Raises:: APIException – If a response was returned indicating the request could not be processed
See:: https://developer.apple.com/documentation/retentionmessaging/delete-message

async extend_renewal_date_for_all_active_subscribers(mass_extend_renewal_date_request: MassExtendRenewalDateRequest) → MassExtendRenewalDateResponse[source]¶

Uses a subscription’s product identifier to extend the renewal date for all of its eligible active subscribers. https://developer.apple.com/documentation/appstoreserverapi/extend_subscription_renewal_dates_for_all_active_subscribers

Parameters:: mass_extend_renewal_date_request – The request body for extending a subscription renewal date for all of its active subscribers.
Returns:: A response that indicates the server successfully received the subscription-renewal-date extension request.
Throws APIException:: If a response was returned indicating the request could not be processed

async extend_subscription_renewal_date(original_transaction_id: str, extend_renewal_date_request: ExtendRenewalDateRequest) → ExtendRenewalDateResponse[source]¶

Extends the renewal date of a customer’s active subscription using the original transaction identifier. https://developer.apple.com/documentation/appstoreserverapi/extend_a_subscription_renewal_date

Parameters:

original_transaction_id – The original transaction identifier of the subscription receiving a renewal date extension.
extend_renewal_date_request – The request body containing subscription-renewal-extension data.

Returns:

A response that indicates whether an individual renewal-date extension succeeded, and related details.

Throws APIException:

If a response was returned indicating the request could not be processed

async get_all_subscription_statuses(transaction_id: str, status: List[Status] | None = None) → StatusResponse[source]¶

Get the statuses for all of a customer’s auto-renewable subscriptions in your app. https://developer.apple.com/documentation/appstoreserverapi/get_all_subscription_statuses

Parameters:

transaction_id – The identifier of a transaction that belongs to the customer, and which may be an original transaction identifier.
status – An optional filter that indicates the status of subscriptions to include in the response. Your query may specify more than one status query parameter.

Returns:

A response that contains status information for all of a customer’s auto-renewable subscriptions in your app.

Throws APIException:

If a response was returned indicating the request could not be processed

async get_app_transaction_info(transaction_id: str) → AppTransactionInfoResponse[source]¶

Get a customer’s app transaction information for your app.

:param transaction_id Any originalTransactionId, transactionId or appTransactionId that belongs to the customer for your app. :return: A response that contains signed app transaction information for a customer. :raises APIException: If a response was returned indicating the request could not be processed :see: https://developer.apple.com/documentation/appstoreserverapi/get-app-transaction-info

async get_image_list() → GetImageListResponse[source]¶

Get the image identifier and state for all uploaded images.

Returns:: A response that contains status information for all images.
Raises:: APIException – If a response was returned indicating the request could not be processed
See:: https://developer.apple.com/documentation/retentionmessaging/get-image-list

async get_message_list() → GetMessageListResponse[source]¶

Get the message identifier and state of all uploaded messages.

Returns:: A response that contains status information for all messages.
Raises:: APIException – If a response was returned indicating the request could not be processed
See:: https://developer.apple.com/documentation/retentionmessaging/get-message-list

async get_notification_history(pagination_token: str | None, notification_history_request: NotificationHistoryRequest) → NotificationHistoryResponse[source]¶

Get a list of notifications that the App Store server attempted to send to your server. https://developer.apple.com/documentation/appstoreserverapi/get_notification_history

Parameters:

pagination_token – An optional token you use to get the next set of up to 20 notification history records. All responses that have more records available include a paginationToken. Omit this parameter the first time you call this endpoint.
notification_history_request – The request body that includes the start and end dates, and optional query constraints.

Returns:

A response that contains the App Store Server Notifications history for your app.

Throws APIException:

If a response was returned indicating the request could not be processed

async get_refund_history(transaction_id: str, revision: str | None) → RefundHistoryResponse[source]¶

Get a paginated list of all of a customer’s refunded in-app purchases for your app. https://developer.apple.com/documentation/appstoreserverapi/get_refund_history

Parameters:

transaction_id – The identifier of a transaction that belongs to the customer, and which may be an original transaction identifier.
revision – A token you provide to get the next set of up to 20 transactions. All responses include a revision token. Use the revision token from the previous RefundHistoryResponse.

Returns:

A response that contains status information for all of a customer’s auto-renewable subscriptions in your app.

Throws APIException:

If a response was returned indicating the request could not be processed

async get_status_of_subscription_renewal_date_extensions(request_identifier: str, product_id: str) → MassExtendRenewalDateStatusResponse[source]¶

Checks whether a renewal date extension request completed, and provides the final count of successful or failed extensions. https://developer.apple.com/documentation/appstoreserverapi/get_status_of_subscription_renewal_date_extensions

Parameters:

request_identifier – The UUID that represents your request to the Extend Subscription Renewal Dates for All Active Subscribers endpoint.
product_id – The product identifier of the auto-renewable subscription that you request a renewal-date extension for.

Returns:

A response that indicates the current status of a request to extend the subscription renewal date to all eligible subscribers.

Throws APIException:

If a response was returned indicating the request could not be processed

async get_test_notification_status(test_notification_token: str) → CheckTestNotificationResponse[source]¶

Check the status of the test App Store server notification sent to your server. https://developer.apple.com/documentation/appstoreserverapi/get_test_notification_status

Parameters:: test_notification_token – The test notification token received from the Request a Test Notification endpoint
Returns:: A response that contains the contents of the test notification sent by the App Store server and the result from your server.
Throws APIException:: If a response was returned indicating the request could not be processed

async get_transaction_history(transaction_id: str, revision: str | None, transaction_history_request: TransactionHistoryRequest, version: GetTransactionHistoryVersion = GetTransactionHistoryVersion.V1) → HistoryResponse[source]¶

Get a customer’s in-app purchase transaction history for your app. https://developer.apple.com/documentation/appstoreserverapi/get_transaction_history

Parameters:

transaction_id – The identifier of a transaction that belongs to the customer, and which may be an original transaction identifier.
revision – A token you provide to get the next set of up to 20 transactions. All responses include a revision token. Note: For requests that use the revision token, include the same query parameters from the initial request. Use the revision token from the previous HistoryResponse.
transaction_history_request – The request parameters that includes the startDate,endDate,productIds,productTypes and optional query constraints.
version – The version of the Get Transaction History endpoint to use. V2 is recommended.

Returns:

A response that contains the customer’s transaction history for an app.

Throws APIException:

If a response was returned indicating the request could not be processed

async get_transaction_info(transaction_id: str) → TransactionInfoResponse[source]¶

Get information about a single transaction for your app. https://developer.apple.com/documentation/appstoreserverapi/get_transaction_info

:param transaction_id The identifier of a transaction that belongs to the customer, and which may be an original transaction identifier. :return: A response that contains signed transaction information for a single transaction. :throws APIException: If a response was returned indicating the request could not be processed

async look_up_order_id(order_id: str) → OrderLookupResponse[source]¶

Get a customer’s in-app purchases from a receipt using the order ID. https://developer.apple.com/documentation/appstoreserverapi/look_up_order_id

Parameters:: order_id – The order ID for in-app purchases that belong to the customer.
Returns:: A response that includes the order lookup status and an array of signed transactions for the in-app purchases in the order.
Throws APIException:: If a response was returned indicating the request could not be processed

async request_test_notification() → SendTestNotificationResponse[source]¶

Ask App Store Server Notifications to send a test notification to your server. https://developer.apple.com/documentation/appstoreserverapi/request_a_test_notification

Returns:: A response that contains the test notification token.
Throws APIException:: If a response was returned indicating the request could not be processed

async send_consumption_data(transaction_id: str, consumption_request: ConsumptionRequest)[source]¶

Send consumption information about a consumable in-app purchase to the App Store after your server receives a consumption request notification. https://developer.apple.com/documentation/appstoreserverapi/send_consumption_information

Parameters:

transaction_id – The transaction identifier for which you’re providing consumption information. You receive this identifier in the CONSUMPTION_REQUEST notification the App Store sends to your server.
consumption_request – The request body containing consumption information.

Raises:

APIException – If a response was returned indicating the request could not be processed

async set_app_account_token(original_transaction_id: str, update_app_account_token_request: UpdateAppAccountTokenRequest)[source]¶

Sets the app account token value for a purchase the customer makes outside your app, or updates its value in an existing transaction. https://developer.apple.com/documentation/appstoreserverapi/set-app-account-token

:param original_transaction_id The original transaction identifier of the transaction to receive the app account token update. :param update_app_account_token_request The request body that contains a valid app account token value. :raises APIException: If a response was returned indicating the request could not be processed

async upload_image(image_identifier: UUID, image: bytes)[source]¶

Upload an image to use for retention messaging.

Parameters:

image_identifier – A UUID you provide to uniquely identify the image you upload.
image – The image file to upload.

Raises:

APIException – If a response was returned indicating the request could not be processed

See:

https://developer.apple.com/documentation/retentionmessaging/upload-image

async upload_message(message_identifier: UUID, upload_message_request_body: UploadMessageRequestBody)[source]¶

Upload a message to use for retention messaging.

Parameters:

message_identifier – A UUID you provide to uniquely identify the message you upload.
upload_message_request_body – The message text to upload.

Raises:

APIException – If a response was returned indicating the request could not be processed

See:

https://developer.apple.com/documentation/retentionmessaging/upload-message

class appstoreserverlibrary.api_client.BaseAppStoreServerAPIClient(signing_key: bytes, key_id: str, issuer_id: str, bundle_id: str, environment: Environment)[source]¶: Bases: object

class appstoreserverlibrary.api_client.GetTransactionHistoryVersion(value)[source]¶

Bases: str, Enum

V1 = 'v1'¶: Deprecated since version 1.3.0.

V2 = 'v2'¶

appstoreserverlibrary.api_client module¶

App Store Server Library

Navigation

Related Topics