Samsung IAP Subscription API
The Samsung IAP Subscription API is used to cancel, refund, revoke, and check the status of Samsung In-App Purchase (IAP) subscription items. Before you can start using the IAP Subscription API, you must meet all requirements, use the required authorization header parameters, and use the required URL path paremeters in your requests. See Get Started with the IAP APIs for more information.
The following is a quick reference to the IAP Subscription APIs:
Name | Request | Description |
---|---|---|
Cancel subscription | PATCH /iap/seller/v6/applications/<packageName>/purchases/subscriptions/<purchaseId> | Cancel the subscription corresponding to the given purchaseId. When a subscription is canceled, automatic payments are no longer made after the current subscription period ends. Customers can use the subscription item until the end of the current subscription period. |
Refund subscription | PATCH /iap/seller/v6/applications/<packageName>/purchases/subscriptions/<purchaseId> | Reimburse the most recent payment for the subscription corresponding to the given purchaseId. The current subscription continues. |
Revoke subscription | PATCH /iap/seller/v6/applications/<packageName>/purchases/subscriptions/<purchaseId> | Immediately cancel the subscription and reimburse the most recent payment for the subscription corresponding to the given purchaseId. When a subscription is revoked, customers instantly lose the ability to use the subscription item, even if the current subscription period has not ended. And, automatic payments are no longer made after the current subscription period ends. |
Check status of subscription | GET /iap/seller/v6/applications/<packageName>/purchases/subscriptions/<purchaseId> | Check the subscription status. |
Cancel, refund, or revoke subscription
Cancel, refund, or revoke a subscription. See the table below for a description of each action.
Request
PATCH /iap/seller/v6/applications/<packageName>/purchases/subscriptions/<purchaseId>
Body parameter
Name | Type | Description |
---|---|---|
action | string | Required. The task to perform. Must be one of the following:
|
curl -i -X PATCH \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your-access-token>" \
-H "service-account-id: <your-service-account-id>" \
-d '{"action" : "cancel | refund | revoke"}' \
'https://devapi.samsungapps.com/iap/seller/v6/applications/<packageName>/items/purchases/subscriptions/<purchaseId>'
Response
Name | Type | Description |
---|---|---|
code | string | Success code, IAP internal error code, or HTTP status code |
message | string | Detailed information about error or HTTP reason |
{
"code" : "0000",
"message" : "Success"
}
See Failure response codes for a list of possible response codes when a request fails.
Check status of subscription
Get the subscription status, including item information and purchase information, which can be used to verify the purchase of an item.
Request
GET /iap/seller/v6/applications/<packageName>/purchases/subscriptions/<purchaseId>
curl -i -X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <your-access-token>" \
-H "service-account-id: <your-service-account-id>" \
'https://devapi.samsungapps.com/iap/seller/v6/applications/<packageName>/items/purchases/subscriptions/<purchaseId>'
Response
Parameters
Parameter | Type | Description |
---|---|---|
subscription |
String | Date and time of the item's initial purchase and payment transaction (YYYY-MM-DD HH:mm:ss GMT) |
subscription |
String | Date and time when the subscription expires (YYYY-MM-DD HH:mm:ss GMT) |
subscriptionStatus | String | Current status of the item subscription"ACTIVE" The subscription is current and in effect."CANCEL" The user canceled the subscription. Check the subscriptionEndDate to see if the subscription period has ended (as the canceled item is still valid until the current suscription period has ended).
|
subscription |
String | Unique identifier of the initial purchase of the item |
countryCode | String | Country code (3 alphabetic characters) of the purchaser's location (for example, KOR, USA) |
price[].localCurrencyCode | String | Currency code (3 alphabetic characters) of the purchaser's local currency paid for the item (for example, EUR, GBP, USD) |
price[].localPrice | double | Cost (in the user's local currency) that the user paid for the in-app item |
price[].supplyPrice | double | Total amount of the item price plus the applied tax |
itemID | String | Unique identifier of the in-app item registered in Seller Portal |
freeTrial | String | Whether or not the in-app item's subscription is currently in a free trial period:"Y" Free trial period"T" Tiered (lower/discounted) price period"N" Regular price period
|
realMode | String | For regular purchases, whether the actual payment was made when the user purchased the item. "Y" Samsung IAP was set to production mode. The actual payment was made."N" Samsung IAP was set to Test Mode. The actual payment was NOT made.
|
latestOrderId | String | Identifier (19 alphanumeric characters) of the most recent payment. it can be an initial payment or a renewal payment. Order IDs are displayed in the user's renewal receipt. |
totalNumberOf |
String | Total number of tiered price payments |
currentPaymentPlan | String | Current period the subscription is in:"F" : Free trial period"R" : Regular price period"T" : Tiered (lower) price period
|
totalNumberOf |
String | Total number of payments made for initial and renewal subscriptions |
cancelSubscription |
String | Date and time the subscription was stopped (YYYY-MM-DD HH:mm:ss GMT) |
cancelSubscription |
String | Cause of the subscription stoppage:"1" User canceled the subscripton."2" System canceled the subscription(for example, renewal test was finished). "3" Billing error (for example, user payment information was no longer valid)."4" Item is not available for purchase at the time of renewal."5" Unknown errors
|
priceChange[].priceChangeMode | String | The mode of the price change:"1" Price increase which requires the user’s consent"2" Price increase which does not require the user’s consent"3" Price decrease, which does not require the user’s consent
|
priceChange[].priceChangeStatus | String | The status of the price change:"WAITING" Waiting for the subscriber to answer"CONFIRMED" The price change is acknowledged by the subscriber (either the subscriber consented or did not consent to the increase in price)"APPLIED" The subscriber is charged the new price
|
priceChange[].priceChangeConsentDate | String | Date and time the subscriber consented (YYYY-MM-DD HH:mm:ss GMT) |
priceChange[].expectedNewPriceChargeDate | String | Date and time the new price will affect the subscriber (YYYY-MM-DD HH:mm:ss GMT) |
priceChange[].newPrice[].localCurrencyCode | String | Local currency code (3 alphabetic characters) of the changed price (for example, EUR, GBP, USD) |
priceChange[].newPrice[].localPrice | double | Cost (in the user's local currency) that the user paid for the in-app item |
Success
{
"subscriptionPurchaseDate": "2024-05-31 01:30:13 GMT",
"subscriptionEndDate": "2024-06-03 01:03:30 GMT",
"subscriptionStatus": "CANCEL",
"subscriptionFirstPurchaseID": "649922f760188d759c19636c4efe130d0743bd6f5446504e0a8e68b0010e0ab7",
"countryCode": "KOR",
"price": {
"localCurrencyCode": "KRW",
"localPrice": 1000.0,
"supplyPrice": 1000.0
},
"itemID": "subsc_30MIN",
"freeTrial": "N",
"realMode": "Y",
"latestOrderId": "S20240531KR01924958",
"totalNumberOfTieredPayment": "0",
"currentPaymentPlan": "R",
"totalNumberOfRenewalPayment": "3",
"cancelSubscriptionDate": "2024-06-03 01:03:29 GMT",
"cancelSubscriptionReason": "2",
"priceChange": {
"priceChangeMode": "1",
"priceChangeStatus": "WAITING",
"priceChangeConsentDate": null,
"expectedNewPriceChargeDate": "2024-05-31 02:22:02 GMT",
"newPrice": {
"localCurrencyCode": "KRW",
"localPrice": 1500.0
}
}
}
See Failure response codes for a list of possible response codes when a request fails.
Failure response codes
Status | Code and message |
---|---|
400 Bad Request |
|
401 Unauthorized |
|
404 Not Found |
|
406 Not Acceptable |
|