Adding Advanced Commerce API objects

README.md

@@ -1,5 +1,5 @@
 # Apple App Store Server Python Library
-The [Python](https://github.com/apple/app-store-server-library-python) server library for the [App Store Server API](https://developer.apple.com/documentation/appstoreserverapi), [App Store Server Notifications](https://developer.apple.com/documentation/appstoreservernotifications), and [Retention Messaging API](https://developer.apple.com/documentation/retentionmessaging). Also available in [Swift](https://github.com/apple/app-store-server-library-swift), [Node.js](https://github.com/apple/app-store-server-library-node), and [Java](https://github.com/apple/app-store-server-library-java).
+The [Python](https://github.com/apple/app-store-server-library-python) server library for the [App Store Server API](https://developer.apple.com/documentation/appstoreserverapi), [App Store Server Notifications](https://developer.apple.com/documentation/appstoreservernotifications), [Retention Messaging API](https://developer.apple.com/documentation/retentionmessaging), and [Advanced Commerce API](https://developer.apple.com/documentation/AdvancedCommerceAPI). Also available in [Swift](https://github.com/apple/app-store-server-library-swift), [Node.js](https://github.com/apple/app-store-server-library-node), and [Java](https://github.com/apple/app-store-server-library-java).
 
 ## Table of Contents
 1. [Installation](#installation)

appstoreserverlibrary/models/AbstractAdvancedCommerceBaseItem.py

@@ -0,0 +1,18 @@
+# Copyright (c) 2026 Apple Inc. Licensed under MIT License.
+
+from abc import ABC
+
+from attr import define
+import attr
+
+from .AdvancedCommerceValidationUtils import AdvancedCommerceValidationUtils
+from .LibraryUtility import AttrsRawValueAware
+
+@define
+class AbstractAdvancedCommerceBaseItem(AttrsRawValueAware, ABC):
+    SKU: str = attr.ib(validator=AdvancedCommerceValidationUtils.sku_validator)
+    """
+    The product identifier of an in-app purchase product you manage in your own system.
+
+    https://developer.apple.com/documentation/advancedcommerceapi/sku
+    """

appstoreserverlibrary/models/AbstractAdvancedCommerceInAppRequest.py

@@ -0,0 +1,14 @@
+# Copyright (c) 2026 Apple Inc. Licensed under MIT License.
+
+from abc import ABC
+
+from attr import define
+import attr
+
+from .AdvancedCommerceRequest import AdvancedCommerceRequest
+from ..jws_signature_creator import AdvancedCommerceAPIInAppRequest
+
+@define
+class AbstractAdvancedCommerceInAppRequest(AdvancedCommerceRequest, AdvancedCommerceAPIInAppRequest, ABC):
+    operation: str = attr.ib()
+    version: str = attr.ib()

appstoreserverlibrary/models/AbstractAdvancedCommerceItem.py

@@ -0,0 +1,23 @@
+# Copyright (c) 2026 Apple Inc. Licensed under MIT License.
+
+from attr import define
+import attr
+
+from .AbstractAdvancedCommerceBaseItem import AbstractAdvancedCommerceBaseItem
+from .AdvancedCommerceValidationUtils import AdvancedCommerceValidationUtils
+
+@define
+class AbstractAdvancedCommerceItem(AbstractAdvancedCommerceBaseItem):
+    description: str = attr.ib(validator=AdvancedCommerceValidationUtils.description_validator)
+    """
+    A string you provide that describes a SKU.
+
+    https://developer.apple.com/documentation/advancedcommerceapi/description
+    """
+
+    displayName: str = attr.ib(validator=AdvancedCommerceValidationUtils.display_name_validator)
+    """
+    A string with a product name that you can localize and is suitable for display to customers.
+
+    https://developer.apple.com/documentation/advancedcommerceapi/displayname
+    """

appstoreserverlibrary/models/AbstractAdvancedCommerceResponse.py

@@ -0,0 +1,23 @@
+# Copyright (c) 2026 Apple Inc. Licensed under MIT License.
+
+from abc import ABC
+from typing import Optional
+
+from attr import define
+import attr
+
+@define
+class AbstractAdvancedCommerceResponse(ABC):
+    signedRenewalInfo: Optional[str] = attr.ib(default=None)
+    """
+    Subscription renewal information, signed by the App Store, in JSON Web Signature (JWS) format.
+
+    https://developer.apple.com/documentation/appstoreserverapi/jwsrenewalinfo
+    """
+
+    signedTransactionInfo: Optional[str] = attr.ib(default=None)
+    """
+    Transaction information signed by the App Store, in JSON Web Signature (JWS) Compact Serialization format.
+
+    https://developer.apple.com/documentation/appstoreserverapi/jwstransaction
+    """

appstoreserverlibrary/models/AdvancedCommerceDescriptors.py

@@ -0,0 +1,27 @@
+# Copyright (c) 2026 Apple Inc. Licensed under MIT License.
+
+from attr import define
+import attr
+
+from .AdvancedCommerceValidationUtils import AdvancedCommerceValidationUtils
+
+@define
+class AdvancedCommerceDescriptors:
+    """
+    The display name and description of a subscription product.
+
+    https://developer.apple.com/documentation/advancedcommerceapi/descriptors
+    """
+    description: str = attr.ib(validator=AdvancedCommerceValidationUtils.description_validator)
+    """
+    A string you provide that describes a SKU.
+
+    https://developer.apple.com/documentation/advancedcommerceapi/description
+    """
+
+    displayName: str = attr.ib(validator=AdvancedCommerceValidationUtils.display_name_validator)
+    """
+    A string with a product name that you can localize and is suitable for display to customers.
+
+    https://developer.apple.com/documentation/advancedcommerceapi/displayname
+    """

appstoreserverlibrary/models/AdvancedCommerceEffective.py

@@ -0,0 +1,14 @@
+# Copyright (c) 2026 Apple Inc. Licensed under MIT License.
+
+from enum import Enum
+
+from .LibraryUtility import AppStoreServerLibraryEnumMeta
+
+class AdvancedCommerceEffective(str, Enum, metaclass=AppStoreServerLibraryEnumMeta):
+    """
+    A string value that indicates when a requested change to an auto-renewable subscription goes into effect.
+
+    https://developer.apple.com/documentation/advancedcommerceapi/effective
+    """
+    IMMEDIATELY = "IMMEDIATELY"
+    NEXT_BILL_CYCLE = "NEXT_BILL_CYCLE"

appstoreserverlibrary/models/AdvancedCommerceOffer.py

@@ -0,0 +1,50 @@
+# Copyright (c) 2026 Apple Inc. Licensed under MIT License.
+from typing import Optional
+
+from attr import define
+import attr
+
+from .AdvancedCommerceOfferPeriod import AdvancedCommerceOfferPeriod
+from .AdvancedCommerceOfferReason import AdvancedCommerceOfferReason
+from .AdvancedCommerceValidationUtils import AdvancedCommerceValidationUtils
+from .LibraryUtility import AttrsRawValueAware
+
+@define
+class AdvancedCommerceOffer(AttrsRawValueAware):
+    """
+    A discount offer for an auto-renewable subscription.
+
+    https://developer.apple.com/documentation/advancedcommerceapi/offer
+    """
+
+    periodCount: int = attr.ib(validator=AdvancedCommerceValidationUtils.period_count_validator)
+    """
+    The number of periods the offer is active.
+    """
+
+    price: int = attr.ib()
+    """
+    The offer price, in milliunits.
+
+    https://developer.apple.com/documentation/advancedcommerceapi/price
+    """
+
+    period: AdvancedCommerceOfferPeriod = AdvancedCommerceOfferPeriod.create_main_attr('rawPeriod', raw_required=True)
+    """
+    The period of the offer.
+    """
+
+    rawPeriod: str = AdvancedCommerceOfferPeriod.create_raw_attr('period', required=True)
+    """
+    See period
+    """
+
+    reason: AdvancedCommerceOfferReason = AdvancedCommerceOfferReason.create_main_attr('rawReason', raw_required=True)
+    """
+    The reason for the offer.
+    """
+
+    rawReason: str = AdvancedCommerceOfferReason.create_raw_attr('reason', required=True)
+    """
+    See reason
+    """

appstoreserverlibrary/models/AdvancedCommerceOfferPeriod.py

@@ -0,0 +1,21 @@
+# Copyright (c) 2026 Apple Inc. Licensed under MIT License.
+
+from enum import Enum
+
+from .LibraryUtility import AppStoreServerLibraryEnumMeta
+
+class AdvancedCommerceOfferPeriod(str, Enum, metaclass=AppStoreServerLibraryEnumMeta):
+    """
+    The period of the offer.
+
+    https://developer.apple.com/documentation/advancedcommerceapi/offer
+    """
+    P3D = "P3D"
+    P1W = "P1W"
+    P2W = "P2W"
+    P1M = "P1M"
+    P2M = "P2M"
+    P3M = "P3M"
+    P6M = "P6M"
+    P9M = "P9M"
+    P1Y = "P1Y"

appstoreserverlibrary/models/AdvancedCommerceOfferReason.py

@@ -0,0 +1,15 @@
+# Copyright (c) 2026 Apple Inc. Licensed under MIT License.
+
+from enum import Enum
+
+from .LibraryUtility import AppStoreServerLibraryEnumMeta
+
+class AdvancedCommerceOfferReason(str, Enum, metaclass=AppStoreServerLibraryEnumMeta):
+    """
+    The reason for the offer.
+
+    https://developer.apple.com/documentation/advancedcommerceapi/offer
+    """
+    ACQUISITION = "ACQUISITION"
+    WIN_BACK = "WIN_BACK"
+    RETENTION = "RETENTION"

appstoreserverlibrary/models/AdvancedCommerceOneTimeChargeCreateRequest.py

@@ -0,0 +1,55 @@
+# Copyright (c) 2026 Apple Inc. Licensed under MIT License.
+
+from typing import Optional
+
+from attr import define
+import attr
+
+from .AbstractAdvancedCommerceInAppRequest import AbstractAdvancedCommerceInAppRequest
+from .AdvancedCommerceOneTimeChargeItem import AdvancedCommerceOneTimeChargeItem
+
+@define
+class AdvancedCommerceOneTimeChargeCreateRequest(AbstractAdvancedCommerceInAppRequest):
+    """
+    The request data your app provides when a customer purchases a one-time-charge product.
+
+    https://developer.apple.com/documentation/advancedcommerceapi/onetimechargecreaterequest
+    """
+
+    currency: str = attr.ib()
+    """
+    The currency of the price of the product.
+
+    https://developer.apple.com/documentation/advancedcommerceapi/currency
+    """
+
+    item: AdvancedCommerceOneTimeChargeItem = attr.ib()
+    """
+    The details of the product for purchase.
+
+    https://developer.apple.com/documentation/advancedcommerceapi/onetimechargeitem
+    """
+
+    taxCode: str = attr.ib()
+    """
+    The tax code for this product.
+
+    https://developer.apple.com/documentation/advancedcommerceapi/taxCode
+    """
+
+    operation: str = attr.ib(init=False, default="CREATE_ONE_TIME_CHARGE", on_setattr=attr.setters.frozen)
+    """
+    The constant that represents the operation of this request.
+    """
+
+    version: str = attr.ib(init=False, default="1", on_setattr=attr.setters.frozen)
+    """
+    The version number of the API.
+    """
+
+    storefront: Optional[str] = attr.ib(default=None)
+    """
+    The storefront for the transaction.
+
+    https://developer.apple.com/documentation/advancedcommerceapi/storefront
+    """

appstoreserverlibrary/models/AdvancedCommerceOneTimeChargeItem.py

@@ -0,0 +1,21 @@
+# Copyright (c) 2026 Apple Inc. Licensed under MIT License.
+
+from attr import define
+import attr
+
+from .AbstractAdvancedCommerceItem import AbstractAdvancedCommerceItem
+
+@define
+class AdvancedCommerceOneTimeChargeItem(AbstractAdvancedCommerceItem):
+    """
+    The details of a one-time charge product, including its display name, price, SKU, and metadata.
+
+    https://developer.apple.com/documentation/advancedcommerceapi/onetimechargeitem
+    """
+
+    price: int = attr.ib()
+    """
+    The price, in milliunits of the currency, of the one-time charge product.
+
+    https://developer.apple.com/documentation/advancedcommerceapi/price
+    """

appstoreserverlibrary/models/AdvancedCommercePeriod.py

@@ -0,0 +1,19 @@
+# Copyright (c) 2026 Apple Inc. Licensed under MIT License.
+
+from enum import Enum
+
+from .LibraryUtility import AppStoreServerLibraryEnumMeta
+
+class AdvancedCommercePeriod(str, Enum, metaclass=AppStoreServerLibraryEnumMeta):
+    """
+    The duration of a single cycle of an auto-renewable subscription.
+
+    https://developer.apple.com/documentation/advancedcommerceapi/period
+    """
+
+    P1W = "P1W"
+    P1M = "P1M"
+    P2M = "P2M"
+    P3M = "P3M"
+    P6M = "P6M"
+    P1Y = "P1Y"

appstoreserverlibrary/models/AdvancedCommerceReason.py

@@ -0,0 +1,15 @@
+# Copyright (c) 2026 Apple Inc. Licensed under MIT License.
+
+from enum import Enum
+
+from .LibraryUtility import AppStoreServerLibraryEnumMeta
+
+class AdvancedCommerceReason(str, Enum, metaclass=AppStoreServerLibraryEnumMeta):
+    """
+    The data your app provides to change an item of an auto-renewable subscription.
+
+    https://developer.apple.com/documentation/advancedcommerceapi/subscriptionmodifychangeitem
+    """
+    UPGRADE = "UPGRADE"
+    DOWNGRADE = "DOWNGRADE"
+    APPLY_OFFER = "APPLY_OFFER"

appstoreserverlibrary/models/AdvancedCommerceRefundReason.py

@@ -0,0 +1,20 @@
+# Copyright (c) 2026 Apple Inc. Licensed under MIT License.
+
+from enum import Enum
+
+from .LibraryUtility import AppStoreServerLibraryEnumMeta
+
+class AdvancedCommerceRefundReason(str, Enum, metaclass=AppStoreServerLibraryEnumMeta):
+    """
+    A reason to request a refund.
+
+    https://developer.apple.com/documentation/advancedcommerceapi/refundreason
+    """
+
+    UNINTENDED_PURCHASE = "UNINTENDED_PURCHASE"
+    FULFILLMENT_ISSUE = "FULFILLMENT_ISSUE"
+    UNSATISFIED_WITH_PURCHASE = "UNSATISFIED_WITH_PURCHASE"
+    LEGAL = "LEGAL"
+    OTHER = "OTHER"
+    MODIFY_ITEMS_REFUND = "MODIFY_ITEMS_REFUND"
+    SIMULATE_REFUND_DECLINE = "SIMULATE_REFUND_DECLINE"

appstoreserverlibrary/models/AdvancedCommerceRefundType.py

@@ -0,0 +1,15 @@
+# Copyright (c) 2026 Apple Inc. Licensed under MIT License.
+
+from enum import Enum
+
+from .LibraryUtility import AppStoreServerLibraryEnumMeta
+
+class AdvancedCommerceRefundType(str, Enum, metaclass=AppStoreServerLibraryEnumMeta):
+    """
+    Information about the refund request for an item, such as its SKU, the refund amount, reason, and type.
+
+    https://developer.apple.com/documentation/advancedcommerceapi/requestrefunditem
+    """
+    FULL = "FULL"
+    PRORATED = "PRORATED"
+    CUSTOM = "CUSTOM"