Most of the order process is done outside the scope of Frisbii Transform. The app provider additionally processes an order on Frisbii Transform by providing order information (receipt) as a replacement for the cart. The Frisbii Transform order process follows the same steps as usual (Create & Commit). Frisbii Transform will verify the passed receipt against the IAP provider. If the receipt is valid, Frisbii Transform will create a customer and a contract as usual.

🚧

Warning

Keep subscriptions of the different IAP platforms and Frisbii Transform in separate contracts at all time. Once a Frisbii Transform contract holds subscriptions of a specific platform do not up/-downgrade to subscriptions of another IAP platform or non-IAP Frisbii Transform subscriptions!

Keeping in mind that Frisbii Transform takes the role of an observer for IAP the order process can be visualized as follows:

Checking IAP subscriptions

Frisbii Transform offers an endpoint to check which subscriptions a receipt contains and which of them are already in Frisbii Transform. To see if a subscription already has a contract in Frisbii Transform, check if the Contract field exists within the returned subscription. If not, you probably want to create an order to add it. This approach can be used to handle receipt restorations.

For Apple, this endpoint can return multiple subscriptions of the same Apple Customer. For other providers, it returns only one subscription.

POST /api/v1/ExternalSubscriptions/check

Apple StoreKit 2

{
     "Type": "AppleIap",
     "AppleIapTransactionId": "...", // required
     "AppleIapBundleId": "..." // optional, defaults to "Default Bundle ID" from the settings
}

Apple StoreKit 1

{
    "Type": "AppleIap",
    "AppleIapReceipt": "..."
}

Google

{
    "Type": "GoogleIap",
    "GoogleIapPackageName": "...",
    "GoogleIapSubscriptionId": "...",
    "GoogleIapToken": "..."
}

Amazon

{
    "Type": "AmazonIap",
    "AmazonIapReceiptId": "...",
    "AmazonIapUserId": "..."
}

Roku

{
    "Type": "RokuPay",
    "RokuPayTransactionId": "..."
}

Response

{
    "Subscriptions":[
        {
            "Id": "<Existing ExternalSubscriptionId>",
            "Contract": { // present if we have a contract for that subscription in Frisbii Transform
                "Id": "<ContractId>",
                "CustomerId": "<CustomerId>"
            }
        }, {
            "Id": "<New ExternalSubscriptionId>"
            // Contract is missing here, so it's not in Frisbii Transform yet
        }
    ]
}

IAP Orders

To create a contract corresponding to an External Subscription, and order needs to be created and committed. This order can add a contract to an existing customer (pass CustomerId) or create a new customer (pass Customer) just like a normal order.

Order after check approach (recommended)

In contrast to non IAP orders, where the Cart property is used, an IAP order accepts an ExternalSubscriptionId at the top level, which can be obtained from the Check REST API endpoint.

This approach works for all providers. For Apple it is the only supported approach.

{
    "ExternalSubscriptionId": "<SubscriptionId>", // returned by `/check`
    "CustomerId": "599d51f823a1610b27a76252",
    "Customer": { // need to pass either CustomerId or Customer, not both
        "FirstName":"Marcellus",
        "LastName":"Wallace"
    },
    ...
}

ExternalCart in order approach (legacy)

Here the same data you'd pass to /check is passed as an ExternalCart in the Order itself. This approach is not supported for Apple. We recommend using the /check based approach for all providers since it's more consistent and robust.

Google Example Request

{
    "CustomerId": "599d51f823a1610b27a76252",
    "Customer": { ... }, // need to pass either CustomerId or Customer, not both
    "ExternalCart": {
        "Type": "GoogleIap",
        "GoogleIapPackageName": "...",
        "GoogleIapSubscriptionId": "...",
        "GoogleIapToken": "..."
    },
    ...
}

Amazon Example Request

{
    "CustomerId": "599d51f823a1610b27a76252",
    "Customer": { ... }, // need to pass either CustomerId or Customer, not both
    "ExternalCart": {
        "Type": "AmazonIap",
        "AmazonIapReceiptId": "...",
        "AmazonIapUserId": "..."
    },
    ...
}