### Example: Upgrade a Subscription

Source: https://developer.apple.com/documentation/AdvancedCommerceAPI/SubscriptionModifyInAppRequest

This example demonstrates how to upgrade a subscription from a monthly to an annual plan, effective immediately, with the billing cycle resetting.

```APIDOC
## POST /api/subscriptions/modify

### Description
Modifies an existing auto-renewable subscription.

### Method
POST

### Endpoint
/api/subscriptions/modify

### Request Body
```json
{
    "operation": "MODIFY_SUBSCRIPTION",
    "version": "1", 
    "transactionId": "12345",
    "requestInfo": {
        "requestReferenceId": "e2a88501-25ba-403a-9c46-d7b8eecc56ba"
    },
    "currency": "USD", 
    "storefront": "USA",
    "descriptors": {
        "effective": "IMMEDIATELY",
        "displayName": "Anne's Game Stream",
        "description": "Streaming Service for Anne's Game"
    },
    "periodChange": {
        "effective": "IMMEDIATELY",
        "period": "P1Y"
    },
    "retainBillingCycle": false,
    "changeItems": [
        {
            "effective": "IMMEDIATELY",
            "currentSKU": "ANNES_GOLD_TIER_1M",
            "SKU": "ANNES_PLATINUM_TIER_1Y",  
            "price": 99990,
            "displayName": "Platinum Tier",
            "description": "Access to Anne's Game Stream & chat",
            "reason": "UPGRADE"
        }
    ]
}
```

### Response
#### Success Response (200)
- **status** (`string`) - Indicates the status of the modification request.
- **subscriptionId** (`string`) - The ID of the modified subscription.
```

--------------------------------

### Example: Add an Item and Retain Billing Cycle

Source: https://developer.apple.com/documentation/advancedcommerceapi/subscriptionmodifyinapprequest

This example shows how to add a new item to a subscription, effective immediately, while keeping the current billing cycle. The customer will be charged a prorated amount for the new item.

```APIDOC
## POST /api/subscriptions/modify

### Description
Modifies an existing auto-renewable subscription by adding new items.

### Method
POST

### Endpoint
`/api/subscriptions/modify`

### Request Body
```json
{
    "operation": "MODIFY_SUBSCRIPTION",
    "version": "1", 
    "transactionId": "12345",
    "requestInfo": {
        "requestReferenceId": "e2a88501-25ba-403a-9c46-d7b8eecc56ba"
    },
    "currency": "USD", 
    "storefront": "USA",
    "descriptors": {
        "effective": "IMMEDIATELY",
        "displayName": "Streaming Pass",
        "description": "Streaming pass with multiple items"
    },
    "retainBillingCycle": true,
    "addItems": [
        {
            "SKU": "NEWS_CHANNELS",    
            "displayName": "News Channel",                            
            "description": "Access to news channels",
            "price": 4990
        }
    ]
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the status of the modification request.
- **transactionId** (string) - The transaction ID for the modification.

#### Response Example
```json
{
  "status": "SUCCESS",
  "transactionId": "12345"
}
```
```

--------------------------------

### Example: Add an Item and Retain Billing Cycle

Source: https://developer.apple.com/documentation/AdvancedCommerceAPI/SubscriptionModifyInAppRequest

This example shows how to add an item to a subscription, effective immediately, while retaining the current billing cycle. The customer will be charged a prorated price for the new item at the next regular billing period.

```APIDOC
## POST /api/subscriptions/modify

### Description
Modifies an existing auto-renewable subscription by adding an item.

### Method
POST

### Endpoint
/api/subscriptions/modify

### Request Body
```json
{
    "operation": "MODIFY_SUBSCRIPTION",
    "version": "1", 
    "transactionId": "12345",
    "requestInfo": {
        "requestReferenceId": "e2a88501-25ba-403a-9c46-d7b8eecc56ba"
    },
    "currency": "USD", 
    "storefront": "USA",
    "descriptors": {
        "effective": "IMMEDIATELY",
        "displayName": "Streaming Pass",
        "description": "Streaming pass with multiple items"
    },
    "retainBillingCycle": true,
    "addItems": [
        {
            "SKU": "NEWS_CHANNELS",    
            "displayName": "News Channel",                            
            "description": "Access to news channels",
            "price": 4990
        }
    ]
}
```

### Response
#### Success Response (200)
- **status** (`string`) - Indicates the status of the modification request.
- **subscriptionId** (`string`) - The ID of the modified subscription.
```

--------------------------------

### Example: Remove an Item at Next Renewal

Source: https://developer.apple.com/documentation/advancedcommerceapi/subscriptionmodifyinapprequest

This example demonstrates how to remove an item from a subscription, with the removal taking effect at the next renewal date. The billing cycle remains unchanged.

```APIDOC
## POST /api/subscriptions/modify

### Description
Modifies an existing auto-renewable subscription by removing items at the next renewal.

### Method
POST

### Endpoint
`/api/subscriptions/modify`

### Request Body
```json
{
    "operation": "MODIFY_SUBSCRIPTION",
    "version": "1", 
    "transactionId": "12345",
    "requestInfo": {
        "requestReferenceId": "e2a88501-25ba-403a-9c46-d7b8eecc56ba"
    },
    "currency": "USD", 
    "storefront": "USA",
    "retainBillingCycle": true,
    "removeItems": [
        {
            "SKU": "LIVE_SPORTS"
        }
    ]
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the status of the modification request.
- **transactionId** (string) - The transaction ID for the modification.

#### Response Example
```json
{
  "status": "SUCCESS",
  "transactionId": "12345"
}
```
```

--------------------------------

### Example: Remove an Item at Next Renewal

Source: https://developer.apple.com/documentation/AdvancedCommerceAPI/SubscriptionModifyInAppRequest

This example demonstrates how to remove an item from a subscription, effective at the next renewal, while retaining the current billing cycle.

```APIDOC
## POST /api/subscriptions/modify

### Description
Modifies an existing auto-renewable subscription by removing an item at the next renewal.

### Method
POST

### Endpoint
/api/subscriptions/modify

### Request Body
```json
{
    "operation": "MODIFY_SUBSCRIPTION",
    "version": "1", 
    "transactionId": "12345",
    "requestInfo": {
        "requestReferenceId": "e2a88501-25ba-403a-9c46-d7b8eecc56ba"
    },
    "currency": "USD", 
    "storefront": "USA",
    "retainBillingCycle": true,
    "removeItems": [
        {
            "SKU": "LIVE_SPORTS"
        }
    ]
}
```

### Response
#### Success Response (200)
- **status** (`string`) - Indicates the status of the modification request.
- **subscriptionId** (`string`) - The ID of the modified subscription.
```

--------------------------------

### Subscription Purchase Request

Source: https://developer.apple.com/documentation/advancedcommerceapi/cancel-a-subscription

Example of a request body for initiating a subscription purchase.

```APIDOC
## POST /subscriptions/purchase

### Description
Initiates a subscription purchase with specified request details and storefront.

### Method
POST

### Endpoint
/subscriptions/purchase

### Request Body
- **requestInfo** (object) - Required - Information about the request, including a unique reference ID.
  - **requestReferenceId** (string) - Required - A unique identifier for the request.
- **storefront** (string) - Required - The storefront from which the purchase is made (e.g., "USA").

### Request Example
```json
{
    "requestInfo": {
        "requestReferenceId": "932c6903-0ab8-4469-9f21-015f6fab013c"
    },
    "storefront": "USA"
}
```

### Response
#### Success Response (200)
- **transactionId** (string) - The unique identifier for the transaction.
- **originalTransactionId** (string) - The identifier of the original transaction, if applicable.
- **webOrderLineItemId** (string) - The line item ID for the web order.
- **bundleId** (string) - The bundle identifier of the app.
- **productId** (string) - The product identifier for the subscription.
- **subscriptionGroupIdentifier** (string) - The identifier for the subscription group.
- **purchaseDate** (integer) - The timestamp when the purchase was made.
- **originalPurchaseDate** (integer) - The timestamp of the original purchase.
- **expiresDate** (integer) - The timestamp when the subscription expires.
- **quantity** (integer) - The quantity of items purchased.
- **type** (string) - The type of subscription (e.g., "Auto-Renewable Subscription").
- **inAppOwnershipType** (string) - The ownership type of the in-app purchase.
- **signedDate** (integer) - The timestamp when the transaction was signed.
- **environment** (string) - The environment where the transaction occurred (e.g., "Production").
- **transactionReason** (string) - The reason for the transaction (e.g., "PURCHASE").
- **storefront** (string) - The storefront where the purchase was made.
- **storefrontId** (string) - The identifier of the storefront.
- **price** (integer) - The price of the subscription.
- **currency** (string) - The currency of the price.
- **appTransactionId** (string) - The transaction ID within the app.
- **appAccountToken** (string) - The account token for the app.
- **advancedCommerceInfo** (object) - Advanced commerce-specific information.
  - **estimatedTax** (integer) - The estimated tax amount.
  - **taxRate** (string) - The tax rate applied.
  - **taxCode** (string) - The tax code.
  - **taxExclusivePrice** (integer) - The price excluding tax.
  - **descriptors** (object) - Descriptive information about the package.
    - **displayName** (string) - The display name of the package.
    - **description** (string) - A description of the package.
  - **items** (array) - A list of items included in the subscription.
    - **SKU** (string) - The Stock Keeping Unit for the item.
    - **displayName** (string) - The display name of the item.
    - **description** (string) - A description of the item.
    - **price** (integer) - The price of the item.
    - **offer** (object) - Details about any special offers.
      - **price** (integer) - The offer price.
      - **period** (string) - The offer period (e.g., "P1M").
      - **periodCount** (integer) - The number of periods for the offer.
      - **reason** (string) - The reason for the offer (e.g., "ACQUISITION").
  - **requestReferenceId** (string) - The reference ID from the original request.
  - **period** (string) - The subscription period (e.g., "P1M").

#### Response Example
```json
{
    "transactionId": "12345",
    "originalTransactionId": "12345",
    "webOrderLineItemId": "23456",
    "bundleId": "com.example",
    "productId": "com.example.base",
    "subscriptionGroupIdentifier": "34567",
    "purchaseDate": 1735718400000,
    "originalPurchaseDate": 1735718400000,
    "expiresDate": 1738396800000,
    "quantity": 1,
    "type": "Auto-Renewable Subscription",
    "inAppOwnershipType": "PURCHASED",
    "signedDate": 1735718400000,
    "environment": "Production",
    "transactionReason": "PURCHASE",
    "storefront": "USA",
    "storefrontId": "143441",
    "price": 12980,
    "currency": "USD",
    "appTransactionId": "45678",
    "appAccountToken": "3152947d-8f63-41c2-9a91-e92e45f145e9",
    "advancedCommerceInfo": {
        "estimatedTax": 0,
        "taxRate": "0",
        "taxCode": "C003-00-1",
        "taxExclusivePrice": 12980,
        "descriptors": {
            "displayName": "Ad-free and advanced feature package",
            "description": "Remove ads and unlock advanced features."
        },
        "items": [
            {
                "SKU": "AD_FREE_1M",
                "displayName": "Ad-free monthly plan",                        
                "description": "Remove ads for the service.",
                "price": 9990
            },
            {
                "SKU": "ADVANCED_FEATURES_1M",
                "displayName": "Advanced feature monthly plan",
                "description": "Unlock advanced features for the month.",
                "price": 3990,
                "offer": {
                    "price": 2990, 
                    "period": "P1M",
                    "periodCount": 3,
                    "reason": "ACQUISITION"
                }
            }
        ],
        "requestReferenceId": "932c6903-0ab8-4469-9f21-015f6fab013c",
        "period": "P1M"
    }
}
```
```

--------------------------------

### Subscription with Multiple Items and an Offer

Source: https://developer.apple.com/documentation/advancedcommerceapi/subscriptioncreaterequest

Example payload for creating a subscription with multiple items, including an offer applied to one of the items.

```json
{
    "operation": "CREATE_SUBSCRIPTION",
    "version": "1", 
    "requestInfo": {
        "requestReferenceId": "74ad2401-488d-4e1a-9c9d-80cdf0efed67"
    },
    "currency": "USD", 
    "taxCode": "C003-00-1", 
    "descriptors": {
        "displayName": "Streaming Pass",
        "description": "Streaming pass with multiple items"
    },
    "period": "P1M",
    "storefront": "USA",
    "items": [ 
        {
            "SKU": "LIVE_SPORTS",
            "displayName": "Live Sports",                        
            "description": "Streaming for sports events",
            "price": 40000
        },
        {
            "SKU": "SATURDAY_MORNING_CARTOONS",
            "displayName": "Saturday Morning Cartoons",
            "description": "Streaming for animated series",
            "price": 11000,
            "offer": {
                "price": 2990, 
                "period": "P1M",
                "periodCount": 3,
                "reason": "ACQUISITION"
            }
        }
    ]
}
```

--------------------------------

### Example: Upgrade a Subscription

Source: https://developer.apple.com/documentation/AdvancedCommerceAPI/SubscriptionModifyInAppRequest

Use this request to upgrade a subscription to a new tier or period, effective immediately. The billing cycle will reset.

```json
{
    "operation": "MODIFY_SUBSCRIPTION",
    "version": "1", 
    "transactionId": "12345",
    "requestInfo": {
        "requestReferenceId": "e2a88501-25ba-403a-9c46-d7b8eecc56ba"
    },
    "currency": "USD", 
    "storefront": "USA",
    "descriptors": {
        "effective": "IMMEDIATELY",
        "displayName": "Anne's Game Stream",
        "description": "Streaming Service for Anne's Game"
    },
    "periodChange": {
        "effective": "IMMEDIATELY",
        "period": "P1Y"
    },
    "retainBillingCycle": false,
    "changeItems": [
        {
            "effective": "IMMEDIATELY",
            "currentSKU": "ANNES_GOLD_TIER_1M",
            "SKU": "ANNES_PLATINUM_TIER_1Y",  
            "price": 99990,
            "displayName": "Platinum Tier",
            "description": "Access to Anne's Game Stream & chat",
            "reason": "UPGRADE"
        }
    ]
}
```

--------------------------------

### Subscription with a Single Item

Source: https://developer.apple.com/documentation/advancedcommerceapi/subscriptioncreaterequest

Example payload for creating a subscription containing one item.

```json
{
    "operation": "CREATE_SUBSCRIPTION",
    "version": "1", 
    "requestInfo": {
        "requestReferenceId": "74ad2401-488d-4e1a-9c9d-80cdf0efed67"
    },
    "currency": "USD", 
    "taxCode": "C003-00-1", 
    "descriptors": {
        "displayName": "Anne's Game Stream",
        "description": "Streaming Service for Anne's Game"
    },
    "period": "P1M",
    "storefront": "USA",
    "items": [ 
        {
            "SKU": "ANNES_GOLD_TIER_1M",
            "displayName": "Gold Tier",                        
            "description": "Access to Anne's Game Stream",
            "price": 7990
        }
    ]
}
```

--------------------------------

### Example: Add an Item and Retain Billing Cycle

Source: https://developer.apple.com/documentation/AdvancedCommerceAPI/SubscriptionModifyInAppRequest

Use this request to add an item to a subscription, effective immediately, while retaining the current billing cycle. The customer will be charged a prorated price for the new item.

```json
{
    "operation": "MODIFY_SUBSCRIPTION",
    "version": "1", 
    "transactionId": "12345",
    "requestInfo": {
        "requestReferenceId": "e2a88501-25ba-403a-9c46-d7b8eecc56ba"
    },
    "currency": "USD", 
    "storefront": "USA",
    "descriptors": {
        "effective": "IMMEDIATELY",
        "displayName": "Streaming Pass",
        "description": "Streaming pass with multiple items"
    },
    "retainBillingCycle": true,
    "addItems": [
        {
            "SKU": "NEWS_CHANNELS",    
            "displayName": "News Channel",                            
            "description": "Access to news channels",
            "price": 4990
        }
    ]
}
```

--------------------------------

### OneTimeChargeCreateRequest JSON Example

Source: https://developer.apple.com/documentation/advancedcommerceapi/onetimechargecreaterequest

A sample JSON payload for a one-time charge request, including required fields like operation, version, and item details.

```json
{
    "operation": "CREATE_ONE_TIME_CHARGE",
    "version": "1",                     
    "requestInfo": {
        "requestReferenceId": "f55df048-4cd8-4261-b404-b6f813ff70e5"
    },
    "currency": "USD",
    "taxCode": "C003-00-2", 
    "storefront": "USA",
    "item": {
        "SKU": "BOOK_SHERLOCK_HOLMES",
        "displayName": "Sherlock Holmes", 
        "description": "The Sherlock Holmes, 5th Edition",
        "price": 4990
    }
}
```

--------------------------------

### NullReasonError Object

Source: https://developer.apple.com/documentation/advancedcommerceapi/nullreasonerror

Details of the NullReasonError object, including its properties and example values.

```APIDOC
## NullReasonError Object

### Description
Represents an error where a required field, specifically 'reason', is missing.

### Properties
- **errorCode** (number) - The error code associated with this error. Value: `4000095`
- **errorMessage** (string) - A descriptive message explaining the error. Value: `The required field, reason, is missing.`

### See Also
- `ACAPriceIncreaseIsNotCurrentlySupportedInIndiaError`
- `AlreadyRefundedError`
- `AtLeastOneItemError`
- `AtLeastOneOfDisplayNameOrDescriptionError`
- `BillingCycleResetWithEffectiveLaterError`
- `ChangeItemNotFoundError`
- `CurrentSKULengthExceededError`
- `DependentSKUsCannotBeChainedError`
- `DependentSKUsCannotBeSharedError`
- `DescriptionLengthExceededError`
- `DisplayNameLengthExceededError`
- `EmptyAddChangeItemsError`
- `FreeTrialOfferMustUsePeriodCountOfOneError`
- `GeneralInternalError`
- `GeneralInternalRetryableError
```

--------------------------------

### Example: Remove an Item at Next Renewal

Source: https://developer.apple.com/documentation/AdvancedCommerceAPI/SubscriptionModifyInAppRequest

Use this request to remove an item from a subscription, effective at the next renewal. The billing cycle remains the same, and remaining items will renew as usual.

```json
{
    "operation": "MODIFY_SUBSCRIPTION",
    "version": "1", 
    "transactionId": "12345",
    "requestInfo": {
        "requestReferenceId": "e2a88501-25ba-403a-9c46-d7b8eecc56ba"
    },
    "currency": "USD", 
    "storefront": "USA",
    "retainBillingCycle": true,
    "removeItems": [
        {
            "SKU": "LIVE_SPORTS"
        }
    ]
}
```

--------------------------------

### Subscription Renewal Status

Source: https://developer.apple.com/documentation/advancedcommerceapi/cancel-a-subscription

Example of a response body detailing the renewal status and advanced commerce information for a subscription.

```APIDOC
## GET /subscriptions/renewal_status

### Description
Retrieves the renewal status and advanced commerce details for a given subscription.

### Method
GET

### Endpoint
/subscriptions/renewal_status

### Query Parameters
- **originalTransactionId** (string) - Required - The original transaction ID of the subscription.

### Response
#### Success Response (200)
- **originalTransactionId** (string) - The original transaction ID of the subscription.
- **autoRenewProductId** (string) - The product ID for auto-renewal.
- **productId** (string) - The product ID of the subscription.
- **autoRenewStatus** (integer) - The auto-renewal status (e.g., 0 for off, 1 for on).
- **signedDate** (integer) - The timestamp when the transaction was signed.
- **environment** (string) - The environment where the transaction occurred.
- **recentSubscriptionStartDate** (integer) - The start date of the most recent subscription period.
- **renewalDate** (integer) - The date when the subscription is set to renew.
- **advancedCommerceInfo** (object) - Advanced commerce-specific information.
  - **taxCode** (string) - The tax code.
  - **descriptors** (object) - Descriptive information about the package.
    - **displayName** (string) - The display name of the package.
    - **description** (string) - A description of the package.
  - **items** (array) - A list of items included in the subscription.
    - **SKU** (string) - The Stock Keeping Unit for the item.
    - **displayName** (string) - The display name of the item.
    - **description** (string) - A description of the item.
    - **price** (integer) - The price of the item.
    - **offer** (object) - Details about any special offers.
      - **price** (integer) - The offer price.
      - **period** (string) - The offer period (e.g., "P1M").
      - **periodCount** (integer) - The number of periods for the offer.
      - **reason** (string) - The reason for the offer (e.g., "ACQUISITION").
  - **requestReferenceId** (string) - The reference ID from the original request.
  - **consistencyToken** (string) - A token for ensuring consistency.
  - **period** (string) - The subscription period (e.g., "P1M").
- **appTransactionId** (string) - The transaction ID within the app.
- **appAccountToken** (string) - The account token for the app.

#### Response Example
```json
{
    "originalTransactionId": "12345",
    "autoRenewProductId": "com.example.base",
    "productId": "com.example.base",
    "autoRenewStatus": 0,
    "signedDate": 1735718400000,
    "environment": "Production",
    "recentSubscriptionStartDate": 1735718400000,
    "renewalDate": 1738396800000,
    "advancedCommerceInfo": {
        "taxCode": "C003-00-1",
        "descriptors": {
            "displayName": "Ad-free and advanced feature package",
            "description": "Remove ads and unlock advanced features."
        },
        "items": [
            {
                "SKU": "AD_FREE_1M",
                "displayName": "Ad-free monthly plan",                        
                "description": "Remove ads for the service.",
                "price": 9990
            },
            {
                "SKU": "ADVANCED_FEATURES_1M",
                "displayName": "Advanced feature monthly plan",
                "description": "Unlock advanced features for the month.",
                "price": 3990,
                "offer": {
                    "price": 2990, 
                    "period": "P1M",
                    "periodCount": 2,
                    "reason": "ACQUISITION"
                }
            }
        ],
        "requestReferenceId": "932c6903-0ab8-4469-9f21-015f6fab013c",
        "consistencyToken": "1.12345.932c6903-0ab8-4469-9f21-015f6fab013c",
        "period": "P1M"
    },
    "appTransactionId": "45678",
    "appAccountToken": "3152947d-8f63-41c2-9a91-e92e45f145e9"
}
```
```

--------------------------------

### InvalidRefundTypeError Object

Source: https://developer.apple.com/documentation/advancedcommerceapi/invalidrefundtypeerror

Details of the InvalidRefundTypeError object, including its properties and example values.

```APIDOC
## InvalidRefundTypeError Object

### Description
Represents an error where the provided refund type is invalid.

### Properties
- **errorCode** (number) - The error code associated with this error. Example: `4000123`
- **errorMessage** (string) - A message describing the error. Example: `The refundType is invalid.`

### See Also
- `ACAPriceIncreaseIsNotCurrentlySupportedInIndiaError`
- `AlreadyRefundedError`
- `AtLeastOneItemError`
- `AtLeastOneOfDisplayNameOrDescriptionError`
- `BillingCycleResetWithEffectiveLaterError`
- `ChangeItemNotFoundError`
- `CurrentSKULengthExceededError`
- `DependentSKUsCannotBeChainedError`
- `DependentSKUsCannotBeSharedError`
- `DescriptionLengthExceededError`
- `DisplayNameLengthExceededError`
- `EmptyAddChangeItemsError`
- `FreeTrialOfferMustUsePeriodCountOfOneError`
- `GeneralInternalError`
- `GeneralInternalRetryableError`
```

--------------------------------

### Define Subscription Product Display Name

Source: https://developer.apple.com/documentation/advancedcommerceapi/creating-skus-for-the-mini-app-partner-program

Sets the product display name for a subscription using the mini app product name.

```text
items.displayName = "Pro Monthly"
```

--------------------------------

### Using RequestInfo in Server Requests

Source: https://developer.apple.com/documentation/advancedcommerceapi/requestinfo

Explains how to use the RequestInfo object in Advanced Commerce API server requests, including optional parameters like appAccountToken and consistencyToken.

```APIDOC
### Include the app account token, optionally

You can include an `appAccountToken` in `RequestInfo` to associate an account on your system with the purchase. The App Store returns the same `appAccountToken` value in the transaction information.

If you include `appAccountToken` in the `RequestInfo`, you don’t need to include the app account token as a purchase option by adding `appAccountToken(_:)` to the product purchase options (`purchase(options:)`).

**Important**: If you do include `appAccountToken` in the `purchase(options:)`, you must include the same app account token value in the `RequestInfo`; otherwise, the request fails.

### Include the consistency token, optionally

The consistency token helps prevent unintended operations that might occur when the server gets multiple or overlapping requests for the same subscription.

Subscriptions receive a new consistency token in the `advancedCommerceRenewalInfo` object of the `JWSRenewalInfo` each time the system updates the subscription renewal information. Include the consistency token when you use the `SubscriptionCreateRequest` operation to resubscribe to the subscription and provide the `previousTransactionID`.

Don’t include a consistency token when:
  * You haven’t received a consistency token.
  * You’re using the `OneTimeChargeCreateRequest` operation.
  * You’re using the `SubscriptionCreateRequest` operation for an initial subscription purchase.
```

--------------------------------

### SubscriptionMigrateItem Object

Source: https://developer.apple.com/documentation/advancedcommerceapi/subscriptionmigrateitem

Represents the SKU, description, and display name to use for a migrated subscription item.

```APIDOC
## SubscriptionMigrateItem Object

### Description
The SKU, description, and display name to use for a migrated subscription item.

### Properties
- **SKU** (string) - Required - The SKU to use for the migrated item. Maximum length: 128.
- **description** (string) - Required - The description of the SKU. Maximum length: 45.
- **displayName** (string) - Required - The display name of the SKU. Maximum length: 30.
```

--------------------------------

### MissingPricingConfigForStorefrontError Object

Source: https://developer.apple.com/documentation/advancedcommerceapi/missingpricingconfigforstorefronterror

Details the properties of the MissingPricingConfigForStorefrontError object.

```APIDOC
## MissingPricingConfigForStorefrontError

### Description
Represents an error indicating that pricing is not configured for the storefront.

### Properties
- **errorCode** (number) - The specific error code, value: 4000134.
- **errorMessage** (string) - The error message, value: "Pricing isn't configured for the storefront."
```

--------------------------------

### Conditional Cancellations and Dependent SKUs

Source: https://developer.apple.com/documentation/advancedcommerceapi/handling-subscription-price-changes

Explains how to handle conditional cancellations where dependent SKUs are canceled if a user does not consent to a price increase.

```APIDOC
## Conditional Cancellations and Dependent SKUs

To create a contingency for a situation in which a person doesn’t agree to a price increase and the App Store cancels other, bundled services (the “dependent SKUs”), you can provide an array of the SKUs through the `dependentSKUs` property. If the price increase requires a person’s consent, and they don’t consent to the price increase (through a cancellation from the Manage Subscriptions view, or by failing to consent before the renewal date), the App Store cancels the dependent SKUs.
```

--------------------------------

### Define Subscription Display Name

Source: https://developer.apple.com/documentation/advancedcommerceapi/creating-skus-for-the-mini-app-partner-program

Sets the display name for a subscription using the mini app name.

```text
descriptors.displayName = "Anne's Game"
```

--------------------------------

### SubscriptionMigrateRenewalItem Object

Source: https://developer.apple.com/documentation/advancedcommerceapi/subscriptionmigraterenewalitem

Defines the structure and properties for the SubscriptionMigrateRenewalItem object used during subscription migration.

```APIDOC
## SubscriptionMigrateRenewalItem

### Description
The item information that replaces a migrated subscription item when the subscription renews.

### Properties
- **SKU** (string) - Required - The SKU that the subscription item renews to at the next renewal period. Maximum length: 128.
- **description** (string) - Required - The description of the renewing SKU. Maximum length: 45.
- **displayName** (string) - Required - The display name of the renewing SKU. Maximum length: 30.
```

--------------------------------

### ProductAlreadyExistsError Object

Source: https://developer.apple.com/documentation/advancedcommerceapi/productalreadyexistserror

Details of the ProductAlreadyExistsError object, which is returned when a product with the provided SKU already exists.

```APIDOC
## ProductAlreadyExistsError

### Description
This error is returned when a product with the provided SKU already exists in the system.

### Properties
- **errorCode** (number) - The error code associated with this error. Value: `4000114`
- **errorMessage** (string) - A message describing the error. Value: `Provided SKU is already owned.`

### See Also
- `ACAPriceIncreaseIsNotCurrentlySupportedInIndiaError`
- `AlreadyRefundedError`
- `AtLeastOneItemError`
- `AtLeastOneOfDisplayNameOrDescriptionError`
- `BillingCycleResetWithEffectiveLaterError`
- `ChangeItemNotFoundError`
- `CurrentSKULengthExceededError`
- `DependentSKUsCannotBeChainedError`
- `DependentSKUsCannotBeSharedError`
- `DescriptionLengthExceededError`
- `DisplayNameLengthExceededError`
- `EmptyAddChangeItemsError`
- `FreeTrialOfferMustUsePeriodCountOfOneError`
- `GeneralInternalError`
- `GeneralInternalRetryableError`
```

--------------------------------

### Define Subscription SKU

Source: https://developer.apple.com/documentation/advancedcommerceapi/creating-skus-for-the-mini-app-partner-program

Sets the unique SKU for a subscription using the format [Mini App SKU Identifier]|[Mini App Partner Name]|[Mini App Partner ID].

```text
items.SKU = "pro_monthly_id|Apple_Seed|WC123"
```

--------------------------------

### SubscriptionCreateItem Object

Source: https://developer.apple.com/documentation/advancedcommerceapi/SubscriptionCreateItem

Details the properties required for the SubscriptionCreateItem object.

```APIDOC
## SubscriptionCreateItem

### Description
The data that describes a subscription item.

### Properties
- **SKU** (string) - Required - The item’s product identifier, which you define. Maximum length: 128.
- **description** (string) - Required - Maximum length: 45.
- **displayName** (string) - Required - Maximum length: 30.
- **offer** (Offer) - Optional - The offer associated with the item.
- **price** (price) - Required - The price of the item.
```

--------------------------------

### ProductNotOwnedError Object

Source: https://developer.apple.com/documentation/advancedcommerceapi/productnotownederror

Details regarding the ProductNotOwnedError object structure and its properties.

```APIDOC
## ProductNotOwnedError

### Description
Represents an error indicating that the customer does not own the requested product.

### Properties
- **errorCode** (number) - The specific error code, value: 4030013.
- **errorMessage** (string) - A descriptive message, value: "The customer doesn't own the product."
```

--------------------------------

### SubscriptionPriceChangeResponse Object

Source: https://developer.apple.com/documentation/advancedcommerceapi/subscriptionpricechangeresponse

Details the structure of the response returned after a subscription price change request.

```APIDOC
## SubscriptionPriceChangeResponse

### Description
A response that contains signed JWS renewal and JWS transaction information after a subscription price change request.

### Properties
- **signedRenewalInfo** (JWSRenewalInfo) - Required - Subscription renewal information signed by the App Store, in JSON Web Signature (JWS) format.
- **signedTransactionInfo** (JWSTransaction) - Required - Transaction information signed by the App Store, in JWS Compact Serialization format.
```

--------------------------------

### ProductNotEligibleError Object

Source: https://developer.apple.com/documentation/advancedcommerceapi/productnoteligibleerror

Details regarding the ProductNotEligibleError object structure and its properties.

```APIDOC
## ProductNotEligibleError

### Description
Represents an error indicating that the product is not eligible for the requested operation.

### Properties
- **errorCode** (number) - The specific error code, value: 4030023.
- **errorMessage** (string) - A descriptive message, value: "The product isn't eligible for the requested operation."
```

--------------------------------

### SubscriptionCreateRequest Object Definition

Source: https://developer.apple.com/documentation/advancedcommerceapi/subscriptioncreaterequest

The base object definition for a subscription creation request.

```text
object SubscriptionCreateRequest
```

--------------------------------

### SubscriptionMigrateDescriptors Object

Source: https://developer.apple.com/documentation/advancedcommerceapi/subscriptionmigratedescriptors

Defines the structure and properties for the SubscriptionMigrateDescriptors object used during subscription migration.

```APIDOC
## SubscriptionMigrateDescriptors

### Description
The SubscriptionMigrateDescriptors object contains the description and display name of the subscription to migrate to that you manage.

### Properties
- **description** (string) - Required - The description of the subscription to migrate to. This string doesn’t display to customers. Maximum length: 45.
- **displayName** (string) - Required - The display name of the subscription to migrate to. This string displays to customers. Maximum length: 30.
```

--------------------------------

### Define One-Time Charge Display Name

Source: https://developer.apple.com/documentation/advancedcommerceapi/creating-skus-for-the-mini-app-partner-program

Sets the display name for a one-time charge using the format [Mini App Name] - [Mini App Product Name].

```text
item.displayName = "Anne’s Game - Boost Pack"
```

--------------------------------

### ProductNotFoundError Object

Source: https://developer.apple.com/documentation/advancedcommerceapi/productnotfounderror

Details regarding the structure and properties of the ProductNotFoundError object.

```APIDOC
## ProductNotFoundError

### Description
Represents an error returned when a product is not found in the system.

### Properties
- **errorCode** (number) - The specific error code, value: 4040016.
- **errorMessage** (string) - The error message, value: "Product not found."
```

--------------------------------

### Notifications and Status Values for Subscription Price Decreases

Source: https://developer.apple.com/documentation/advancedcommerceapi/handling-subscription-price-changes

Details the notifications and status values for subscription price change items that decrease a price.

```APIDOC
## Notifications and Status Values for Subscription Price Decreases

This table describes the notifications and status values for a subscription price change item that decreases a price:

| Notification type | Subtype | Property details | Description |
|---|---|---|---|
| `PRICE_CHANGE` | - | - | Indicates that you called the `Change Subscription Price` endpoint. This notification only applies to apps that use the Advanced Commerce API. |
| `DID_RENEW` | - | - | Indicates the SKU renewed. Always to check to ensure `JWSRenewalInfo` and the `JWSTransaction` information to provide service to the list items. |
```

--------------------------------

### Advanced Commerce API Data Types

Source: https://developer.apple.com/documentation/advancedcommerceapi/datatypes

Overview of the objects and data types used for subscription management and product configuration.

```APIDOC
## Objects

- **Descriptors**: The display name and description of a subscription product.
- **Offer**: A discount offer for an auto-renewable subscription.
- **RequestInfo**: The metadata to include in server requests.
- **SubscriptionModifyAddItem**: Data provided to add items when changing an auto-renewable subscription.
- **SubscriptionModifyChangeItem**: Data provided to change an item of an auto-renewable subscription.
- **SubscriptionModifyDescriptors**: Data provided to change the description and display name of an auto-renewable subscription.
- **SubscriptionModifyPeriodChange**: Data provided to change the period of an auto-renewable subscription.
- **SubscriptionModifyRemoveItem**: Data provided to remove an item from an auto-renewable subscription.
- **SubscriptionPriceChangeItem**: Data provided to change a subscription price.

## Data Types

- **currency**: Three-letter ISO 4217 currency code.
- **description**: String describing a SKU.
- **dependentSKU**: Product identifier of a dependent SKU in a price change.
- **displayName**: Localizable product name for display.
- **effective**: String indicating when a change goes into effect.
- **period**: Duration of a single subscription cycle.
- **price**: Price in milliunits of a currency.
- **proratedPrice**: Prorated price in milliunits of a currency.
- **retainBillingCycle**: Boolean to keep existing billing cycle.
- **refundAmount**: Refund amount in milliunits of the currency.
- **refundReason**: Reason for a refund request.
- **refundRiskingPreference**: Boolean indicating if consumption data is requested.
- **SKU**: Product identifier for an in-app purchase.
- **storefront**: Three-letter code for the App Store storefront.
- **taxCode**: Tax code applied to a SKU.
- **targetProductId**: Generic identifier for product migration.
- **transactionId**: Unique identifier generated by the App Store.
- **version**: Version number of the data structure.
```

--------------------------------

### StorefrontChangeError Object

Source: https://developer.apple.com/documentation/advancedcommerceapi/storefrontchangeerror

Details the structure and properties of the StorefrontChangeError object.

```APIDOC
## StorefrontChangeError

### Description
Represents an error indicating that the storefront has changed.

### Properties
- **errorCode** (number) - The specific error code, value: 4030022.
- **errorMessage** (string) - The error message, value: "The storefront changed."
```

--------------------------------

### Object: Descriptors

Source: https://developer.apple.com/documentation/advancedcommerceapi/Descriptors

Defines the structure of the Descriptors object, which contains the display name and description for a subscription product.

```APIDOC
## Object: Descriptors

### Description
The display name and description of a subscription product.

### Properties
- **description** (string) - Required - A string that contains a description of the product. This string is not displayed to customers. Maximum length: 45.
- **displayName** (string) - Required - A string that contains the name of the product, suitable for display to customers. Maximum length: 30.
```

--------------------------------

### Offer Object Definition

Source: https://developer.apple.com/documentation/advancedcommerceapi/offer

Defines the structure and properties of an Offer object used for subscription discounts in the Advanced Commerce API.

```APIDOC
## Offer Object

A discount offer for an auto-renewable subscription.

### Properties

`period` (string) - Required - The period of the offer. Possible Values: `P3D, P1W, P2W, P1M, P2M, P3M, P6M, P9M, P1Y`
`periodCount` (int32) - Required - The number of periods the offer is active. Minimum: `1`, Maximum: `12`
`price` (price) - Required - The offer price, in milliunits.
`reason` (string) - Required - The reason for the offer. Possible Values: `ACQUISITION, WIN_BACK, RETENTION`
```

--------------------------------

### NullStorefrontError Object

Source: https://developer.apple.com/documentation/advancedcommerceapi/nullstorefronterror

Details regarding the NullStorefrontError object structure and its properties.

```APIDOC
## NullStorefrontError

### Description
Represents an error occurring when the required 'storefront' field is missing in an API request.

### Properties
- **errorCode** (number) - The specific error code: 4000100.
- **errorMessage** (string) - The error message: 'The required field, storefront, is missing.'
```

--------------------------------

### Data Type: effective

Source: https://developer.apple.com/documentation/advancedcommerceapi/effective

Defines the timing for subscription changes within the Advanced Commerce API.

```APIDOC
## Data Type: effective

### Description
A string value that indicates when a requested change to an auto-renewable subscription goes into effect.

### Possible Values
- **IMMEDIATELY**: The requested change goes into effect immediately.
- **NEXT_BILL_CYCLE**: The requested change goes into effect at the start of the next billing cycle.
```

--------------------------------

### SubscriptionAlreadyMigratedError Object

Source: https://developer.apple.com/documentation/advancedcommerceapi/subscriptionalreadymigratederror

Details of the SubscriptionAlreadyMigratedError object, including its properties and fixed values.

```APIDOC
## SubscriptionAlreadyMigratedError

### Description
Represents an error where a subscription has already been migrated.

### Properties
- **errorCode** (number) - The error code associated with this error. Value: `4000176`
- **errorMessage** (string) - A message describing the error. Value: `The subscription was already migrated.`
```

--------------------------------

### Define One-Time Charge SKU

Source: https://developer.apple.com/documentation/advancedcommerceapi/creating-skus-for-the-mini-app-partner-program

Sets the unique SKU for a one-time charge using the format [Mini App SKU Identifier]|[Mini App Partner Name]|[Mini App Partner ID].

```text
item.SKU = "boost_pack_id |Apple_Seed|WC123"
```

--------------------------------

### SubscriptionMigrateRequest Object

Source: https://developer.apple.com/documentation/advancedcommerceapi/subscriptionmigraterequest

The SubscriptionMigrateRequest object contains the details required to migrate a subscription from In-App Purchase to the Advanced Commerce API. This includes descriptors, items, renewal items, request information, storefront, target product ID, and tax code.

```APIDOC
## SubscriptionMigrateRequest Object

### Description
The subscription details you provide to migrate a subscription from In-App Purchase to the Advanced Commerce API, such as descriptors, items, storefront, and more.

### Properties
- **descriptors** (SubscriptionMigrateDescriptors) - Required - The description and display name of the subscription to migrate to.
- **items** (Array[SubscriptionMigrateItem]) - Required - An array of one or more SKUs, along with descriptions and display names, that are included in the subscription.
- **renewalItems** (Array[SubscriptionMigrateRenewalItem]) - Optional - An optional array of subscription items that represents the items that renew at the next renewal period, if they differ from `items`. Supply this array if the customer has a pending subscription downgrade or cross-grade, which applies at the next renewal period.
- **requestInfo** (RequestInfo) - Required
- **storefront** (storefront) - Optional
- **targetProductId** (string) - Required - Your generic product ID for an auto-renewable subscription. You configure this product ID in App Store Connect during setup.
- **taxCode** (string) - Required

### See Also
- `Migrate a Subscription to Advanced Commerce API`
- `object SubscriptionMigrateResponse`
- `object SubscriptionMigrateItem`
- `object SubscriptionMigrateRenewalItem`
- `object SubscriptionMigrateDescriptors`
```

--------------------------------

### SubscriptionReactivateInAppRequest Object

Source: https://developer.apple.com/documentation/AdvancedCommerceAPI/SubscriptionReactivateInAppRequest

Defines the request structure for reactivating an in-app subscription.

```APIDOC
## SubscriptionReactivateInAppRequest

### Description
The request your app provides to reactivate a subscription that has automatic renewal turned off.

### Properties
- **items** ([SubscriptionReactivateItem]) - Optional - List of items to reactivate.
- **operation** (string) - Required - Value: REACTIVATE_SUBSCRIPTION.
- **requestInfo** (RequestInfo) - Required - Information about the request.
- **storefront** (storefront) - Optional - The storefront associated with the request.
- **transactionId** (transactionId) - Required - The transaction ID to reactivate.
- **version** (version) - Required - The API version.
```

--------------------------------

### AtLeastOneOfDisplayNameOrDescriptionError Object

Source: https://developer.apple.com/documentation/advancedcommerceapi/atleastoneofdisplaynameordescriptionerror

This object represents an error that occurs when neither a display name nor a description is provided for a resource.

```APIDOC
## AtLeastOneOfDisplayNameOrDescriptionError

### Description
This error is returned when a request requires either a `displayName` or a `description` to be present, but neither was provided.

### Properties
#### errorCode (number)
- **Value**: `4000165`
- **Description**: The specific error code for this validation failure.

#### errorMessage (string)
- **Value**: `Provide either the displayName or a description.`
- **Description**: A human-readable message explaining the error.

### See Also
- `ACAPriceIncreaseIsNotCurrentlySupportedInIndiaError`
- `AlreadyRefundedError`
- `AtLeastOneItemError`
- `BillingCycleResetWithEffectiveLaterError`
- `ChangeItemNotFoundError`
- `CurrentSKULengthExceededError`
- `DependentSKUsCannotBeChainedError`
- `DependentSKUsCannotBeSharedError`
- `DescriptionLengthExceededError`
- `DisplayNameLengthExceededError`
- `EmptyAddChangeItemsError`
- `FreeTrialOfferMustUsePeriodCountOfOneError`
- `GeneralInternalError`
- `GeneralInternalRetryableError`
- `InactiveACASubError`
```